---
title: "List eval runs"
method: GET
path: "/org/evals/runs"
tags: ["Evals"]
---

# List eval runs

`GET /org/evals/runs`

## Request

- Base URL: `https://apiv2.senso.ai/api/v1`
- URL: `https://apiv2.senso.ai/api/v1/org/evals/runs`
- Auth: API key in header `X-API-Key`

Returns one page of your organization's eval runs, newest first, with each run's status and headline metrics. The bulky payloads — the subject snapshot, claims, searches, and evidence — are left to the single-run read. Filter by creation time, evaluator, and subject type.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `evaluator` string
- `subject_type` string
- `limit` integer
- `offset` integer

## Response `200`

One page of eval runs.

- EvalRunListResponse: One page of eval runs.
  - `items` EvalRunSummary[], required: The runs on this page, newest first.
    - `eval_run_id` string, uuid, required
    - `evaluator_key` string, required: The evaluator that ran, e.g. `kb_accuracy` or `brand_alignment`.
    - `evaluator_version` string, required: The evaluator version this run was pinned to.
    - `status` 'queued' | 'running' | 'completed' | 'gated' | 'failed' | 'canceled', required: `queued` — waiting for a worker. `running` — being judged. `completed` — judged, with metrics and claims. `gated` — a pre-check found nothing to judge (an empty answer or a refusal), so the run ended with no model spend; the reason is under `outputs.gates` in the run detail. `failed` — the judgment could not complete; see `error_code` and `error_message`. `canceled` is reserved and not currently produced. A run is finished when its status is `completed`, `gated`, or `failed`.
    - `subject_type` 'content' | 'content_generation_run_item' | 'builder_workspace_version' | 'question_run' | 'search_turn' | 'inline', required: What was judged — `inline` for text supplied to `POST /org/evals/text`, `content` for a saved content item. Other values belong to runs triggered elsewhere in Senso.
    - `subject_id` string, uuid: The judged item's id — the `content_id` for a content run. Absent for inline text.
    - `subject_version_id` string, uuid: The exact content version that was judged. Absent for inline text.
    - `judge_model` string, required: The model that judged the text.
    - `label` string: The label supplied on the trigger, if any.
    - `metrics` object, nullable: The evaluator's reported metrics, keyed as its metric descriptors describe them (`GET /org/evals/evaluators`). For `kb_accuracy` these are `accuracy_pct`, `coverage_pct`, `contradiction_pct`, and `band`, plus `grounding_failures` and `kb_internal_conflicts` when non-zero. For `brand_alignment` they are the metrics its descriptors list, such as `brand_score` and `brand_verdict`. Present once the run has completed.
    - `claims_total` integer: Claims extracted from the text. Present once the run has completed; `0` for `brand_alignment`, which grades rules rather than claims.
    - `claims_scored` integer: Claims that counted toward the score — those about your brand and verifiable. Present once completed; `0` for `brand_alignment`.
    - `accuracy_pct` number: Share of scored claims the knowledge base verified, 0–100. Claim-based evaluators only.
    - `band` 'green' | 'yellow' | 'red': Traffic-light reading of `accuracy_pct` against the evaluator's cut-offs. Claim-based evaluators only.
    - `total_cost` number: Judge model spend for this run, in US dollars. Recorded for transparency; not billed to your credits.
    - `error_code` string: Why a `failed` run failed, e.g. `judge_failed` or `dispatch_failed`.
    - `error_message` string: Detail for `error_code`.
    - `created_at` string, date-time, required
    - `finished_at` string, date-time: When the run reached a finished status. Absent while queued or running.
  - `total` integer, required: Total runs matching the filters, across all pages.
  - `limit` integer, required: The page size that was applied.
  - `offset` integer, required: The offset that was applied.

## Other responses

- `400`: The request was malformed — a bad path/query parameter or an invalid value.
- `401`: Missing or invalid credentials — supply a valid org API key in the `X-API-Key` header.

---

[API](https://skmtc.dev/senso/apis/senso-org-api.md) - [All operations](https://skmtc.dev/senso/apis/senso-org-api/llms.txt) - [OpenAPI document](https://skmtc.dev/senso/apis/senso-org-api/revisions/d789b4fcbe84?raw)