> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiforgeo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List tasks, newest first

> Without results: read one task for its result. Pass nextCursor as cursor for the next page.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/tasks
openapi: 3.1.0
info:
  title: API for GEO
  version: 1.0.0
  description: >
    Send a prompt to an AI model in a country and a language. Get back,
    asynchronously, the model's answer with its entities and their sentiment,
    its sources, the web searches it ran (fan-outs), its products and its ads.


    ## Authentication


    Send an API key from the dashboard with every request: `Authorization:
    Bearer afg_live_...`.


    ## Money


    Amounts are integer micro-dollars: `costMicros: 13000` is $0.013. A task is
    charged when it is created, and refunded if it fails. Send an
    `Idempotency-Key` header to retry a creation safely: the same key returns
    the first task, charged once.


    ## Test keys


    A test key (`afg_test_...`) runs in a sandbox: it is never charged, and the
    result is a sample of the live shape. A prompt with `[fail]` in it fails;
    `[slow]` takes about 2 minutes; any other prompt completes in about 15
    seconds.


    ## Results


    A completed task's result is readable for 7 days after completion
    (`resultExpiresAt`). After that, `result` is null. The task itself, with its
    cost and its metadata, stays. Save what you need within the 7 days.


    ## Errors


    Every error has one shape: `{ "error": { "code", "message", "details",
    "requestId" } }`. Act on `code`; quote `requestId` to support.


    ## Webhooks


    Pass `webhookUrl` on a task, or add endpoints in the dashboard. API for GEO
    then POSTs events:


    ```json

    { "type": "task.completed", "timestamp": "2026-10-24T12:00:05.000Z", "data":
    { "id": "task_...", "status": "completed", "result": {} } }

    ```


    | Event | `data` |

    | --- | --- |

    | `task.completed` | The task, with its result |

    | `task.failed` | The task, with `error`, and `refunded: true` for a live
    key |

    | `balance.low`, `balance.depleted` | `currency`, `balanceMicros`,
    `lowBalanceThresholdMicros` |


    A task's `webhookUrl` gets that task's two events. Answer with a 2xx within
    10 seconds. Anything else is sent again after 5 seconds, 5 minutes, 30
    minutes, then 2, 5, 10 and 10 hours. An endpoint that fails all through
    those 27 hours is turned off, and the organization's owners and admins get
    an email.


    ### Verify the signature


    Deliveries follow [Standard Webhooks](https://www.standardwebhooks.com).
    Each one has three headers:


    - `webhook-id`: the event id, the same on every retry. Use it to drop a
    duplicate.

    - `webhook-timestamp`: Unix seconds.

    - `webhook-signature`: `v1,` and the base64 HMAC-SHA256 of
    `<id>.<timestamp>.<body>`. The key is your secret without `whsec_`,
    base64-decoded. During a secret rotation, two signatures come, separated by
    a space: accept either.


    Check the raw body, before you parse it:


    ```js

    import { createHmac, timingSafeEqual } from 'node:crypto';


    function verifyWebhook(secret, headers, rawBody) {
      const id = headers['webhook-id'];
      const timestamp = headers['webhook-timestamp'];
      if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; // older than 5 minutes: a replay
      const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
      const expected = Buffer.from(`v1,${createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest('base64')}`);
      return headers['webhook-signature'].split(' ').some((candidate) => {
        const given = Buffer.from(candidate);
        return given.length === expected.length && timingSafeEqual(given, expected);
      });
    }

    ```


    A Standard Webhooks library does the same in one call, in many languages. An
    endpoint's secret is shown when you add it or rotate it. The deliveries to a
    task's `webhookUrl` use the organization's task webhook secret, in the
    dashboard.
servers:
  - url: https://api.apiforgeo.com
security: []
paths:
  /v1/tasks:
    get:
      tags:
        - Tasks
      summary: List tasks, newest first
      description: >-
        Without results: read one task for its result. Pass nextCursor as cursor
        for the next page.
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
          required: false
          name: limit
          in: query
        - schema:
            type: string
            pattern: ^[a-z]+_[0-9a-f]{32}$
          required: false
          name: cursor
          in: query
        - schema:
            type: string
            enum:
              - queued
              - processing
              - completed
              - failed
              - running
            description: '`running`: queued or processing.'
          required: false
          description: '`running`: queued or processing.'
          name: status
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 200
            description: A task id, or words of the prompt.
          required: false
          description: A task id, or words of the prompt.
          name: q
          in: query
        - schema:
            type: string
          required: false
          name: model
          in: query
        - schema:
            type: string
          required: false
          name: apiKeyId
          in: query
        - schema:
            type: string
            format: date-time
            description: Created at or after, ISO 8601.
          required: false
          description: Created at or after, ISO 8601.
          name: from
          in: query
        - schema:
            type: string
            format: date-time
            description: Created before, ISO 8601.
          required: false
          description: Created before, ISO 8601.
          name: to
          in: query
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                  nextCursor:
                    type:
                      - string
                      - 'null'
                required:
                  - items
                  - nextCursor
        '400':
          description: See error.code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: See error.code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKey: []
components:
  schemas:
    Task:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum:
            - queued
            - processing
            - completed
            - failed
        mode:
          type: string
          enum:
            - live
            - test
        prompt:
          type: string
        model:
          type: string
        country:
          type: string
        language:
          type: string
        enrichments:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties:
            type: string
        webhookUrl:
          type:
            - string
            - 'null'
        costMicros:
          type: integer
          description: >-
            What the task was charged, in micro-dollars: 13000 is $0.013. 0 for
            a test key.
        refunded:
          type: boolean
        apiKeyId:
          type:
            - string
            - 'null'
        createdAt:
          type: string
        startedAt:
          type:
            - string
            - 'null'
        completedAt:
          type:
            - string
            - 'null'
        failedAt:
          type:
            - string
            - 'null'
        error:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
            message:
              type: string
          required:
            - code
            - message
        resultExpiresAt:
          type:
            - string
            - 'null'
          description: >-
            When the result stops being readable: 7 days after completion. Null
            until the task completes.
        result:
          $ref: '#/components/schemas/TaskResult'
      required:
        - id
        - status
        - mode
        - prompt
        - model
        - country
        - language
        - enrichments
        - metadata
        - webhookUrl
        - costMicros
        - refunded
        - apiKeyId
        - createdAt
        - startedAt
        - completedAt
        - failedAt
        - error
        - resultExpiresAt
        - result
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: insufficient_balance
            message:
              type: string
            details:
              type:
                - object
                - 'null'
              additionalProperties: {}
            requestId:
              type: string
          required:
            - code
            - message
            - details
            - requestId
      required:
        - error
    TaskResult:
      type:
        - object
        - 'null'
      properties:
        answer:
          type: string
          description: The model's answer, as it gave it (markdown).
        entities:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
                example: brand
              position:
                type:
                  - integer
                  - 'null'
              mentions:
                type: integer
              sentiment:
                type:
                  - number
                  - 'null'
                description: From -1 (negative) to +1 (positive). Null when not scored.
                example: 0.8
              stance:
                type:
                  - string
                  - 'null'
                enum:
                  - chosen
                  - described
                  - named
                  - dismissed
                  - criticized
                  - null
                description: How the answer treats the entity. Null when not judged.
                example: chosen
            required:
              - name
              - type
              - position
              - mentions
              - sentiment
              - stance
        sources:
          type: array
          items:
            type: object
            properties:
              url:
                type:
                  - string
                  - 'null'
              domain:
                type: string
              title:
                type:
                  - string
                  - 'null'
              position:
                type:
                  - integer
                  - 'null'
            required:
              - url
              - domain
              - title
              - position
        fanOuts:
          type: array
          items:
            type: object
            properties:
              phrase:
                type: string
                example: best running shoes for flat feet 2026
            required:
              - phrase
          description: The web searches the model ran while it answered, in its order.
        products:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              brand:
                type:
                  - string
                  - 'null'
              price:
                $ref: '#/components/schemas/Money'
              rating:
                type:
                  - number
                  - 'null'
              reviewCount:
                type:
                  - integer
                  - 'null'
              imageUrl:
                type:
                  - string
                  - 'null'
              position:
                type: integer
              merchants:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                    url:
                      type:
                        - string
                        - 'null'
                    price:
                      $ref: '#/components/schemas/Money'
                  required:
                    - name
                    - url
                    - price
            required:
              - name
              - brand
              - price
              - rating
              - reviewCount
              - imageUrl
              - position
              - merchants
        ads:
          type: array
          items:
            type: object
            properties:
              position:
                type: integer
              format:
                type:
                  - string
                  - 'null'
                description: The ad format, as the engine names it.
              advertiser:
                type:
                  - string
                  - 'null'
                description: Who paid for the ad.
              brand:
                type:
                  - string
                  - 'null'
              title:
                type:
                  - string
                  - 'null'
              body:
                type:
                  - string
                  - 'null'
              imageUrl:
                type:
                  - string
                  - 'null'
              url:
                type:
                  - string
                  - 'null'
              price:
                $ref: '#/components/schemas/Money'
              strikethroughPrice:
                allOf:
                  - $ref: '#/components/schemas/Money'
                  - description: The crossed-out price beside it, when the ad shows one.
              rating:
                type:
                  - number
                  - 'null'
            required:
              - position
              - format
              - advertiser
              - brand
              - title
              - body
              - imageUrl
              - url
              - price
              - strikethroughPrice
              - rating
          description: The sponsored cards shown with the answer.
      required:
        - answer
        - entities
        - sources
        - fanOuts
        - products
        - ads
      description: >-
        Once completed, on GET /v1/tasks/{taskId} only, for 7 days
        (resultExpiresAt). Null after that; the task stays.
    Money:
      type:
        - object
        - 'null'
      properties:
        amountMicros:
          type: integer
        currency:
          type: string
      required:
        - amountMicros
        - currency
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An API key from the dashboard: `afg_live_…` or `afg_test_…`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.