> ## 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.

# Get status

> Check Entity Search task progress and readable result count.

Returns the latest progress for a task created by the same API key. A terminal status request can also complete billing settlement.

## Example

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

## Response

```json theme={null}
{
  "object": "entity_search_status",
  "leads_search_id": "leads_search_01JABCDEF123456789",
  "status": {
    "status": "running",
    "ready_count": 10,
    "verified_count": 12
  }
}
```

| Field                   | Description                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `status.status`         | `created`, `running`, `done`, or `error`.                                                             |
| `status.ready_count`    | Results currently available through Fetch.                                                            |
| `status.verified_count` | Candidates checked so far, including accepted and rejected candidates; always at least `ready_count`. |
| `status.stop_reason`    | Terminal reason when available; omitted otherwise.                                                    |
| `status.error`          | The fixed value `internal error` for a failed task; omitted otherwise.                                |

Known `stop_reason` values include `limit`, `source_finished`, `no_data_timeout`, and `rejected_streak`. Treat new values as forward-compatible strings.

<Note>
  A task with `status: error` can still have a positive `ready_count`. Fetch those completed results before closing the task locally.
</Note>

Status is available only to the exact API key that created the task. A missing task and a task owned by another key 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/status
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/status:
    get:
      summary: Get status
      description: Check Entity Search task progress and readable result count.
      operationId: getEntitySearchStatus
      parameters:
        - name: leads_search_id
          in: query
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 128
            x-default: leads_search_01JABCDEF123456789
          example: leads_search_01JABCDEF123456789
      responses:
        '200':
          description: Task status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntitySearchStatus'
        '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:
    EntitySearchStatus:
      type: object
      properties:
        object:
          type: string
          const: entity_search_status
        leads_search_id:
          type: string
          example: leads_search_01JABCDEF123456789
        status:
          type: object
          properties:
            status:
              type: string
              enum:
                - created
                - running
                - done
                - error
              example: running
            verified_count:
              type: integer
              minimum: 0
              example: 12
            ready_count:
              type: integer
              minimum: 0
              example: 10
            stop_reason:
              type: string
              example: source_finished
            error:
              type: string
              const: internal error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      x-default: lev8_live_...

````