---
title: "Poll Eval Job"
method: GET
path: "/v1/eval-runs/{eval_run_id}"
tags: ["Eval Jobs"]
---

# Poll Eval Job

`GET /v1/eval-runs/{eval_run_id}`

## Request

- Base URL: `https://api.lightsage.com`
- URL: `https://api.lightsage.com/v1/eval-runs/{eval_run_id}`
- Auth: API key in header `X-Lightsage-Api-Key`

Returns the status and progress of a durable eval job.

The `eval_run_id` is the `id` returned by `POST /v1/eval-runs`. Progress is
computed from the parent job, its dispatch, and child jobs. Poll this
endpoint until `status` reaches a terminal value.

## Path parameters

- `eval_run_id` string, required

## Response `200`

Successful Response

- PublicEvalRunResponse
  - `id` string, required: Job ID for polling; not a result ID from `GET /v1/api-performance/runs`.
  - `job_id` string, required: The parent job ID. It currently contains the same polling ID as `id`.
  - `type` 'prompts' | 'api_performance', required
  - `source_type` 'prompts' | 'rest_api' | 'sdk' | 'cli' | 'custom_evals', required
  - `status` union, required: Terminal values: `completed`, `failed`, and `cancelled`. Recoverable interruptions are reported as `running` with stage `retrying`.
    - 'pending' | 'running' | 'summarizing' | 'completed' | 'failed' | 'cancelled' | 'interrupted'
    - string
  - `stage` string, nullable: Current lifecycle stage, including `retrying` while interrupted child jobs wait to be reclaimed.
  - `dispatch_id` string, nullable
  - `progress` PublicEvalRunProgress
    - `total` integer
    - `queued` integer
    - `running` integer
    - `completed` integer
    - `failed` integer
    - `cancelled` integer
    - `retrying` integer: Recoverable child jobs waiting to be retried. These remain active and are excluded from `percent`.
    - `interrupted` integer: Deprecated compatibility alias for `retrying`; use `retrying`.
    - `percent` number: The percentage of child jobs in a final state (`completed`, `failed`, or `cancelled`). It can reach `100` while the parent job is still summarizing, so use `status` to detect completion.
  - `estimated_cost` number, nullable: Estimated credits for the run, worked out when it was queued. Credits actually used can differ by agent and model. Null when no estimate is available.
  - `eval_count` integer, nullable
  - `model_count` integer, nullable
  - `error` string, nullable
  - `created_at` string, nullable
  - `started_at` string, nullable
  - `completed_at` string, nullable: Can be set while `status` is still `summarizing`; use `status` to detect completion.

## Other responses

- `404`: The eval job does not exist or is not visible to this API key.
- `422`: Validation Error

---

[API](https://skmtc.dev/usesapient/apis/sapient-public-api.md) - [All operations](https://skmtc.dev/usesapient/apis/sapient-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usesapient/apis/sapient-public-api/revisions/14890dfe867e?raw)