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

# Fetch results

> Read Entity Search results by position.

Fetches results that are already available for a task. Fetch can be called while the task is running and after either terminal state.

`pts` defaults to `0`. `num` defaults to `5` and must be between `1` and `500`.

## Example

```bash theme={null}
curl --get "https://app.lev8.com/v1/entity-search/fetch" \
  --header "x-api-key: $LEV8_API_KEY" \
  --data-urlencode "leads_search_id=leads_search_01JABCDEF123456789" \
  --data-urlencode "pts=0" \
  --data-urlencode "num=5"
```

## Response

```json theme={null}
{
  "object": "entity_search_items",
  "status": "running",
  "leads_search_id": "leads_search_01JABCDEF123456789",
  "pts": 0,
  "num": 5,
  "count": 2,
  "ready_count": 2,
  "limit": 20,
  "entities": [
    {
      "name": "Figure AI",
      "links": {
        "website": "https://www.figure.ai"
      },
      "description": "AI robotics company building general purpose humanoid robots.",
      "score": {
        "score": "high",
        "reason": "Matches the objective."
      }
    }
  ]
}
```

The API does not return a cursor. Calculate the next position as `pts + count`. The task is fully consumed only when `status` is `done` or `error` and your next position is at least `ready_count`.

Fetch is available only to the API key that created the task. Missing and cross-key tasks both return `404 not_found`.

See [Task results](/api-reference/task-results) for the complete polling and fetch loop.


## OpenAPI

````yaml GET /v1/entity-search/fetch
openapi: 3.1.0
info:
  title: lev8 API
  version: '1.0'
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
  - url: https://app.lev8.com
security:
  - ApiKeyAuth: []
paths:
  /v1/entity-search/fetch:
    get:
      summary: Fetch results
      description: Read available Entity Search results by position.
      operationId: fetchEntitySearchResults
      parameters:
        - name: leads_search_id
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            x-default: leads_search_01JABCDEF123456789
          example: leads_search_01JABCDEF123456789
        - name: pts
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
            x-default: 0
          example: 0
        - name: num
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 5
            x-default: 5
          example: 5
      responses:
        '200':
          description: Current result items.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySearchItems'
        '401':
          description: Missing or invalid API key.
        '403':
          description: API key is forbidden or lacks Entity Search access.
        '404':
          description: Task not found or belongs to another API key.
        '422':
          description: Query validation failed.
        '500':
          description: Server error.
        '503':
          description: Entity Search is not enabled.
components:
  schemas:
    EntitySearchItems:
      type: object
      properties:
        object:
          type: string
          const: entity_search_items
        leads_search_id:
          type: string
          example: leads_search_01JABCDEF123456789
        status:
          type: string
          example: running
        pts:
          type: integer
          example: 0
        num:
          type: integer
          example: 5
        count:
          type: integer
          example: 5
        ready_count:
          type: integer
          example: 10
        limit:
          type: integer
          example: 20
        entities:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                example: Figure AI
              links:
                type: object
                additionalProperties:
                  type: string
                example:
                  website: https://www.figure.ai
                  linkedin_url: https://www.linkedin.com/company/figure-ai
              description:
                type:
                  - string
                  - 'null'
                example: AI robotics company building general purpose humanoid robots.
              score:
                type: object
                properties:
                  score:
                    type: string
                    example: high
                  reason:
                    type: string
                    example: ...
              enrich_fields:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    content:
                      type: string
                    reference:
                      type: string
                example:
                  funding stage:
                    content: Series B
                    reference: ...
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      x-default: lev8_live_...

````