---
title: "Start Eval Job"
method: POST
path: "/v1/eval-runs"
tags: ["Eval Jobs"]
---

# Start Eval Job

`POST /v1/eval-runs`

## Request

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

Queues a durable eval job and returns immediately with its polling ID.

For prompt evals, provide explicit `targets` to override the configured
prompt targets, or omit `targets` to use the organization's configured
scheduled prompt targets. For API Performance evals, explicit `targets` or
`models` override the stored configuration; when omitted, Lightsage uses
configured scheduled targets or legacy configured models. For eval runs
with `source_type` set to `custom_evals`, `custom_eval_ids` identify the evals
to run, while `targets`
specify the text models or coding-agent harness and model combinations used
for the run. Omit `custom_eval_ids` to use the configured eval set.

For API Performance source types backed by a source (`rest_api`, `sdk`, or
`cli`), provide `source_id` from `api-performance sources list`, or omit it
when `operation_ids`, `eval_ids`, or the requested `source_type` identify a
single source. `operation_ids` are Lightsage API Performance operation IDs,
not OpenAPI operationId strings.

Every run is queued through the durable job queue. The response `id` is the
`eval_run_id` to pass to `GET /v1/eval-runs/{eval_run_id}`. When Lightsage can
determine the runnable work, the response also includes `dispatch_id` and
initial queued progress for the child jobs. If neither the request nor the
saved configuration identifies runnable work, the request fails with `400`.
If the organization lacks the estimated credits, it fails with `402` before
dispatching work.
An environment containing an empty or placeholder credential also fails with
`400` before any evaluation is dispatched.

## Request body

- union
  - PublicPromptEvalRunRequest
    - `type` 'prompts', required
    - `prompt_ids` string[], nullable: Omit to run all active prompts.
    - `targets` PublicPromptEvalRunTarget[], nullable: Omit to use the configured scheduled targets.
      - `target_kind` 'answer_engine' | 'coding_agent', required: The execution mode for this target. Use `credits_per_prompt` from `GET /v1/prompts/config` for its current credit cost.
      - `execution_platform` string, required
      - `prompt_platform_id` string, required: Platform ID from GET /v1/prompts/config.
      - `model_id` string, required
      - `prompt_topic_id` string, nullable: Topic ID from GET /v1/prompts/config.
      - `search_grounding` 'disabled' | 'enabled' | 'default': Requested web-retrieval behavior for an eval run.
      - `enabled` boolean
    - `force` boolean: Re-run even if the prompt already ran today on that platform and model.
  - PublicApiPerformanceEvalRunRequest
    - `type` 'api_performance', required
    - `source_type` 'rest_api' | 'sdk' | 'cli' | 'custom_evals', required: Use `custom_evals` to run evals selected by `custom_eval_ids`; the other values run a configured API Performance source.
    - `source_id` string: Source ID from GET /v1/api-performance/sources. Required unless operation_ids, eval_ids, or source_type identify one source.
    - `models` string[], nullable: Legacy model selection; prefer `targets`.
    - `targets` PublicApiPerformanceEvalRunTarget[], nullable: Targets for the selected evals. Agent targets pair an `agent_id` harness with a supported `model_id`; text targets use `model_id` only. Omit to use saved configuration.
      - `target_type` 'text' | 'agent', required: Use `text` for a `text_models` entry or `agent` for a `coding_agents` entry from `GET /v1/api-performance/targets`. Under Pricing V2, coding-agent targets are usage-based. Legacy agent targets cost 5 credits. Text targets cost 1 credit.
      - `agent_id` string, nullable: Coding agent ID from GET /v1/api-performance/targets; required only for agent targets.
      - `model_id` string, required: text_models[].id for a text target, or an id from the agent's models list, both from GET /v1/api-performance/targets.
      - `enabled` boolean
    - `categories` string[], nullable
    - `operation_ids` string[], nullable: operation_id values from GET /v1/api-performance/evals, not OpenAPI operationIds.
    - `operation_paths` string[], nullable: METHOD:path filters, such as GET:/v1/items.
    - `eval_ids` string[], nullable: Eval configuration IDs from GET /v1/api-performance/evals.
    - `custom_eval_ids` string[], nullable: Eval IDs from GET /v1/api-performance/custom-evals identifying which evals to run. Used only when source_type is custom_evals.
    - `eval_types` string[], nullable: eval_type values from GET /v1/api-performance/evals.
    - `env_profile_ids` string[], nullable: Environment profile IDs from `env_profiles[].id` in `GET /v1/api-performance/config`.
    - `eval_overrides` object, nullable

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

- `400`: The request is valid, but Lightsage could not determine what to run from either the request payload or saved configuration.
- `402`: The organization does not currently have enough credits for the requested run.
- `403`: One or more requested targets are unavailable on the organization's current plan.
- `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)