API reference

This page lists every Evals REST endpoint and what it returns.

Every endpoint is a GET under https://<your-deployment>/api/v1/evals and needs a task key with Read evals, sent as Authorization: Bearer <task-api-key> or X-API-Key: <task-api-key>. Writes go through the CLI.

The full parameter and response schema for every endpoint is in the OpenAPI 3.1 file, which ships next to this guide as openapi.yaml and openapi.json. Load it into your HTTP client or code generator. Your deployment also serves its own copy without a key: the OpenAPI 3.0.3 file at /api/v1/evals/openapi.json, and a page you can browse at /api/v1/evals/docs.

Some list endpoints page with cursor or page; Limits and requests says which. Required query parameters are shown in the path column.

Evaluations, datasets and runs

Method and path	What it returns
`GET /benchmarks`	The workspace’s evaluations.
`GET /benchmarks/{evaluationId}`	One evaluation, with its axes and judge model.
`GET /benchmarks/{evaluationId}/datasets`	The links between an evaluation and its datasets, as rows of `{id, evaluationId, datasetId, order}`.
`GET /benchmarks/{evaluationId}/runs`	An evaluation’s runs, in no set order. Sort by `createdAt`.
`GET /datasets`	The workspace’s datasets.
`GET /datasets/{datasetId}`	One dataset: name, description, owner and visibility.
`GET /datasets/{datasetId}/items`	A dataset’s tasks.
`GET /items/{taskId}`	One dataset task: prompt, expected answer and file IDs. The ID is the one the CLI calls `<item-id>`.
`GET /runs/{runId}`	One run: its axes, cells, counts, average score and cost.
`GET /runs/{runId}/status`	A run as the Runs table shows it: each cell’s score, the best cell, cost per task and criteria that errored.
`GET /runs/{runId}/tasks?cellId=`	One cell’s tasks, each with its score, criteria results, answer preview, cost and latency.
`GET /runs/{runId}/tasks/{taskId}?cellId=`	One task’s full result: the full answer and every criterion’s reasoning.

Traces and usage

Method and path	What it returns
`GET /traces/sessions?from=&to=`	Trace sessions, latest activity first.
`GET /traces/sessions/{sessionId}`	One session’s summary and its model calls, one window at a time: pass `nextCursor` back as `cursor` for the rest.
`GET /traces/calls?from=&to=`	Model calls, one row per model turn.
`GET /traces/payloads?chatId=&messageId=&partIndex=&day=`	The full content of one message part.
`GET /traces/histogram?from=&to=`	Session and error counts over time.
`GET /traces/filter-options`	The models, providers, agents and users that have trace data.
`GET /traces/agents/{agentId}/profile?since=`	One agent’s cost, tokens and daily usage.
`GET /traces/users/{userId}/profile?since=`	One user’s cost, tokens and usage by agent.
`GET /traces/cost-dashboard?since=`	Cost across the organization, by agent, by day and by skill.

Analytics

Method and path	What it returns
`GET /analytics/records`	Analytics records (tasks, sub-agent tasks and dispatch runs), with filters.
`GET /analytics/overview`	Summary numbers and chart series for the matching records.
`GET /analytics/options`	The values you can filter analytics by.
`GET /analytics/records/export`	Every matching record as line-delimited JSON.
`GET /analytics/records/{recordId}`	One record with its latest run and feedback.

GET /analytics/records, GET /analytics/overview and GET /analytics/records/export take workflowIds to keep only records whose chat is in one of those workflows. Records and trace sessions list their workflows in the response (workflows); a run carries the workflow it was started from as topicId.

Feedback, judges and scorecards

Method and path	What it returns
`GET /feedback/enabled`	Whether feedback is on for the whole deployment.
`GET /feedback/schemas`	The feedback forms (scorecard versions) in your organization.
`GET /feedback`	Feedback entries.
`GET /judges`	Saved judges: instructions, output type and model.
`GET /judges/{judgeId}`	One saved judge.
`GET /scorecards`	The automatic feedback scorecards. The skill rubrics that `context evals scorecard` manages are not served over HTTP.
`GET /scorecards/{scorecardId}`	One scorecard, its questions and where it applies.
`GET /scorecards/scope-options`	The workspaces and users a scorecard can apply to.

What the API leaves out

Monitors and their results, and every write, are in the CLI and the app only. Workflow setup is in the app only. A trace session that a monitor’s agent judge ran in carries origin.monitor with the monitor’s ID and name.