---
title: "Get an eval run"
method: GET
path: "/org/evals/runs/{runId}"
tags: ["Evals"]
---

# Get an eval run

`GET /org/evals/runs/{runId}`

## Request

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

Returns everything about one run: its status and metrics, the subject as it was judged, every claim with its verdict and evidence, and the judge's audit trail — every search it ran and every passage it read — so a verdict can be checked rather than trusted. This is the poll target for a queued run; the run is finished when `status` is `completed`, `gated`, or `failed`.

## Path parameters

- `runId` string, uuid, required

## Response `200`

The run.

- EvalRunDetail: Everything about one run — the poll target and the audit record. This is the only place the judge's full working is returned.
  - `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.
  - `subject` object: The subject exactly as it was judged, so later edits cannot change what a verdict refers to. For inline text: `title` and `text`. For a content item: `content_id`, `content_version_id`, `version_num`, `title`, `editorial_status`, and `text`.
  - `outputs` object, nullable: Structured detail too bulky or too shaped for `metrics`, present once the run has been processed. Includes `gates`, the pre-check result (`passed`, `answer_produced`, `is_refusal`, `sources_present`, and `reason` and `detail` when the run was gated). `kb_accuracy` adds `mode`, `relevance_floor`, and `search_type`; `brand_alignment` adds its full review under `brand_alignment`. `extraction_salvaged` or `result_salvaged` flag a run whose model output had to be partially recovered.
  - `claims` EvalClaim[], required: Every claim — or, for `brand_alignment`, every graded writing rule — with its verdict. Empty until the run completes, and for gated or failed runs.
    - `eval_claim_id` string, uuid, required
    - `eval_run_id` string, uuid, required
    - `evaluator_key` string, required
    - `subject_type` 'content' | 'content_generation_run_item' | 'builder_workspace_version' | 'question_run' | 'search_turn' | 'inline', required: The run's subject type.
    - `claim_key` string, required: The claim's identifier within its run (`c1`, `c2`, …). For `brand_alignment`, the writing rule that was graded.
    - `claim_text` string, required: The statement that was judged, in the judge's words. For a brand rule, the quoted passage that was graded, or `Rule N: <rule text>` when the reviewer quoted nothing.
    - `item_hash` string, required: A stable hash of the claim text, so the same statement can be recognised across runs.
    - `source_text` string: The sentence in the subject the claim was extracted from.
    - `kind` string: What sort of claim it is — normally `numeric`, `entity`, `procedural`, `modal`, or `other`. `kb_accuracy` only.
    - `about_brand` boolean: Whether the claim is about your organization. General knowledge is never checked against the knowledge base.
    - `verifiable` boolean: Whether a document could settle the claim. Subjective claims are excluded from scoring.
    - `verdict` string: The evaluator's own vocabulary. `kb_accuracy`: `verified`, `conflict`, `unsupported`, or `not_verifiable`. `brand_alignment`: `pass`, `partial`, `fail`, `not_applicable`, or `ungraded`. Absent when the claim was excluded before verification, or when the judge returned no verdict for a checkable claim — which scores as unsupported.
    - `passed` boolean, nullable, required: The normalized signal — `true` passed, `false` failed, `null` excluded from scoring rather than failing.
    - `bucket` string, required: The claim's classification. For knowledge-base checks on text and content: `general` (not about your brand), `subjective`, `grounded`, `contradicts_kb`, or `unsupported_by_kb`. For checks on cited answers: `ok`, `kb_gap`, `generation_error`, `kb_conflict_or_retrieval`, or `retrieval_miss`. For `brand_alignment` rows it carries the rule identifier.
    - `confidence` string: The judge's confidence in the verdict — normally `high`, `medium`, or `low`.
    - `reasoning` string: Why the judge reached the verdict.
    - `quote` string: The verbatim knowledge-base sentence the verdict rests on, checked against the retrieved text before the verdict was allowed to stand. Present on positive verdicts.
    - `grounding_failed` boolean: True when the verdict was demoted because its quote or citation was not in the retrieved text — the judge asserting support that was not there. Distinct from an honest `unsupported`.
    - `grounding_problem` string: What was wrong with the grounding, when `grounding_failed` is true.
    - `original_verdict` string: The verdict before demotion, when `grounding_failed` is true.
    - `suggested_fix` string: A concrete rewording for a failing claim or rule.
    - `evidence` EvalClaimEvidence[], nullable: The knowledge-base passages the verdict rests on.
      - `content_id` string, required: The content item the passage came from. An empty string marks a citation the judge gave that could not be matched to any retrieved passage; such verdicts are demoted (see `grounding_failed` on the claim).
      - `chunk_index` integer
      - `content_version_id` string, uuid
      - `relation` string, required: How the passage bears on the claim — normally `entails`, `contradicts`, or `related`.
    - `evidence_was_cited` boolean: Whether the evidence came from a source the judged answer itself cited. Only meaningful for cited-answer subjects; for text and content subjects it is `false` whenever evidence is present. Absent when the claim has no evidence.
    - `created_at` string, date-time, required
  - `searches` EvalSearchRecord[], nullable: Every knowledge-base search the judge ran, in order. `kb_accuracy` only.
    - `query` string, required: The search the judge issued.
    - `scoped_to_cited` boolean, required: True when the search was restricted to the sources the judged answer itself cited. Always false for text and content subjects.
    - `max_results` integer, required: How many passages the judge asked for.
    - `n_results` integer, required: How many it got back.
    - `result_content_ids` string[], nullable, required: The content items the returned passages came from. `null` when the search returned nothing.
    - `result_titles` string[]: Titles of those content items, when known.
    - `top_score` number: The highest relevance score among the results.
    - `error` string: Present when the search itself failed.
  - `evidence_chunks` EvalEvidenceChunk[], nullable: Every knowledge-base passage the judge read while verifying claims. `kb_accuracy` only.
    - `content_id` string, uuid, required
    - `chunk_index` integer, required: The passage's position within its content item.
    - `title` string: The content item's title, when known.
    - `score` number: Relevance score from the search that returned it.
    - `text` string, required: The passage as the judge saw it.
    - `truncated` boolean: True when the passage was cut to fit the judge's context.
  - `searches_over_budget` integer: Searches the judge wanted to run beyond its budget. Non-zero means some claims were judged on less evidence than the judge asked for.
  - `usage` EvalUsage, required: What the judgment cost. Recorded, not billed.
    - `api_calls` integer
    - `input_tokens` integer
    - `output_tokens` integer
    - `cached_tokens` integer
    - `total_cost` number: In US dollars.
    - `split` object, nullable: The same figures by stage — `extraction` (claim extraction) and the evaluator's key.

## 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.
- `404`: The requested resource does not exist or is not visible to this key.

---

[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)