--- title: "Get an evaluation sandbox run" method: GET path: "/api/v2/evaluation-runs/{runId}" tags: ["Evaluations"] --- # Get an evaluation sandbox run `GET /api/v2/evaluation-runs/{runId}` ## Request - Base URL: `https://davinci-app.com` - URL: `https://davinci-app.com/api/v2/evaluation-runs/{runId}` - Auth: one of: - HTTP bearer - HTTP bearer Reads lifecycle, quality, evidence, and cleanup state. The Code execution's own grant or the user credential behind it may read the run. Tokens are returned only to the execution grant while the sandbox is live. ## Response `200` Current evaluation-run state. - EvaluationRun - `runId` string, uuid, required - `sourceProjectId` string, required - `testId` string, nullable: The Test whose Results Value started the Code, when a Test did. Absent for a Code object run directly. - `testRunId` string, uuid, nullable: The Test run that started the Code, when one did. - `codeExecutionId` string - `sessionId` string, uuid: Headless target session attached to the evaluation data-plane grant. - `status` 'provisioning' | 'ready' | 'running' | 'cleaning' | 'cleaned' | 'failed' | 'expired', required: `ready` means the target is pinned and its grant can be used. `failed` is an infrastructure failure, not a low quality score. `cleaned` and `expired` are terminal and carry no usable grant. - `sandbox` EvaluationSandbox, required - `projectId` string, required: Server-chosen target project. It is never accepted from the create body. - `branchName` string, required - `name` string - `ephemeral` boolean, required: Always true for an evaluation-created target. - `deleteAfter` string, date-time - `dataPlane` EvaluationDataPlaneAccess: Everything needed to address the data plane: where to send, what to send with, and the path parameters that are not obvious from the project id alone. - `url` string, uri, required: Base URL for data-plane operations. Names no specific machine, so it stays valid if the project moves. - `token` string, required: The grant, `dav_gr_…`. Returned only here and only once — it is not stored in recoverable form, so a lost grant is replaced by refreshing the session rather than looked up. - `expiresAt` string, date-time, required - `connectionId` string, required: Pass as the `connectionId` path parameter on upload. - `ownerId` string, required: Pass as the `ownerId` path parameter. - `userId` string, required: Pass as the `userId` path parameter on upload. - `projectKey` string, required: Pass as the `projectId` path parameter. Compound form `{projectId}--{branchName}`, since the data plane addresses a branch. - `operations` string[], required: Data-plane operations this grant authorizes. - `purpose` 'evaluation', required: Target-bound evaluation authority. Ordinary data-plane/execution grants remain denied from agent and git routes; this purpose admits only the target agent, and still denies git. - `evidence` EvaluationEvidence - `capturedAt` string, date-time, required - `transcript` AgentTranscript, required - `sessionId` string, uuid, required - `taskId` string, required - `source` 'live' | 'persisted' | 'none', required: Where the answer came from. `live` is current; `persisted` is the copy saved when a run ended, and so lags a run in progress. - `status` 'no_session' | 'project_not_running' | 'idle' | 'starting' | 'running' | 'paused' | 'completed' | 'failed' | 'unknown', required: - `no_session` — the machine has no record of this session; it lapsed or the project restarted. Create a new one. - `project_not_running` — the session is known but its project has unloaded. - `idle` — the session is live and no run has been started. - `starting` — a run is being set up. - `running` — a run is in progress. - `paused` — a run was stopped and can be continued with a new prompt. - `completed` — the run finished. - `failed` — the run ended in an error. `agent.error` says why, as does the transcript. - `unknown` — the machine could not be reached for this field. Retry; anything else in the same response is still valid. `paused`, `completed`, and `failed` are terminal for a run. - `entryCount` integer, required: Entries in the whole conversation, not just the returned window. - `messages` AgentMessage[], required: Oldest first. Bounded by `limit`, taken from the end. - `index` integer, required: Position in the whole conversation, so a window can be placed. - `role` 'user' | 'agent', required - `kind` string, required: `text` for what was said, `thought` for the agent's reasoning, `tool` for a tool it used, `error` for a failure it hit. Treat an unrecognized value as informational rather than as a problem — new kinds can appear. - `text` string: The content. For a `tool` entry, the tool's name. - `timestamp` integer, nullable: Milliseconds since the epoch. - `messageId` string: Present on your own prompts, matching what you sent. - `tool` AgentToolUse: Present only on entries whose `kind` is `tool`. - `name` string, nullable - `status` string, nullable: `working` while it runs, `complete` when it succeeded, otherwise the severity of what went wrong. - `params` unknown - `result` unknown - `error` string: Present when the tool failed. - `tree` ProjectTree, required: Flat list of project objects excluding the project object itself. New projects contain reserved `Model` and `Library` packages whose `parent` is the project id; callers must not assume a parentless node exists. - `objectCount` integer, required: Total objects in the project, including the project object itself. - `tree` TreeNode[], required - `id` string, required - `name` string, required - `type` string, required - `parent` string, nullable - `childrenCount` integer - `usage` UsageResponse, required - `scope` 'account' | 'project' | 'session', required: What the numbers cover, determined by the path you called. - `projectId` string: Present on the project and session reads. Always the bare id. - `sessionId` string, uuid: Present on the session read. - `asOf` string, date-time, nullable, required: When the newest counted event was recorded, or null when the scope holds none. This is the honest bound on freshness: the engine reports usage on an interval, so a run's last few seconds may not be included. Null means "nothing here", not "nothing yet" — a scope with no usage looks the same either way, and inventing a timestamp would hide that. - `totals` UsageTotals, required - `amountUsd` number, required: Dollars charged (USD), to six decimal places. - `promptTokens` integer, required - `completionTokens` integer, required - `reasoningTokens` integer, required: Thinking tokens, charged at the completion rate. - `cacheWriteTokens` integer, required - `cacheReadTokens` integer, required - `eventCount` integer, required: Charged calls counted. Not all of them are token-priced — image generation and web search are charged per call, so a non-zero `amountUsd` with zero tokens is normal rather than a gap. - `groupBy` 'model' | 'project' | 'session' | 'day': Echoed back when you asked for a breakdown. - `groups` UsageGroup[]: One entry per group, largest spend first — except `day`, which is chronological. Absent unless you passed `groupBy`. - `amountUsd` number, required: Dollars charged (USD), to six decimal places. - `promptTokens` integer, required - `completionTokens` integer, required - `reasoningTokens` integer, required: Thinking tokens, charged at the completion rate. - `cacheWriteTokens` integer, required - `cacheReadTokens` integer, required - `eventCount` integer, required: Charged calls counted. Not all of them are token-priced — image generation and web search are charged per call, so a non-zero `amountUsd` with zero tokens is normal rather than a gap. - `provider` string, nullable: Present when grouping by model. - `model` string, nullable: Present when grouping by model. - `projectId` string, nullable: Present when grouping by project. - `sessionId` string, nullable: Present when grouping by session. - `day` string, date-time, nullable: Midnight UTC of the day. Present when grouping by day. - `seededObjectIds` string[] - `artifacts` object[] - `name` string, required - `mediaType` string - `fileId` string - `sha256` string - `summary` object - `quality` QualityObservation - `value` number, required: Finite numeric observation returned to native Test evaluation criteria. - `unit` string - `rubric` string - `metrics` object - `failure` RunFailure - `code` 'EVALUATION_SCOPE_MISSING' | 'EVALUATION_AGENT_FAILED' | 'EVALUATION_TIMEOUT' | 'EVALUATION_EVIDENCE_MISSING' | 'EVALUATION_OBSERVATION_INVALID' | 'EVALUATION_CLEANUP_FAILED' | 'CODE_EXECUTION_FAILED' | 'TEST_CANCELLED' | 'TEST_RUN_FAILED' | 'TEST_RUN_TIMED_OUT', required - `message` string, required - `infrastructure` boolean, required: True when no quality verdict may be inferred from this failure. - `details` object - `cleanup` EvaluationCleanup, required - `status` 'not_started' | 'pending' | 'completed' | 'failed', required - `requested` boolean, required - `requestedAt` string, date-time - `completedAt` string, date-time - `grantsRevoked` integer - `projectDeleted` boolean - `failure` RunFailure - `code` 'EVALUATION_SCOPE_MISSING' | 'EVALUATION_AGENT_FAILED' | 'EVALUATION_TIMEOUT' | 'EVALUATION_EVIDENCE_MISSING' | 'EVALUATION_OBSERVATION_INVALID' | 'EVALUATION_CLEANUP_FAILED' | 'CODE_EXECUTION_FAILED' | 'TEST_CANCELLED' | 'TEST_RUN_FAILED' | 'TEST_RUN_TIMED_OUT', required - `message` string, required - `infrastructure` boolean, required: True when no quality verdict may be inferred from this failure. - `details` object - `createdAt` string, date-time, required - `expiresAt` string, date-time, required - `updatedAt` string, date-time ## Other responses - `401`: No credential was supplied, or the supplied credential is malformed, expired, or revoked. A credential that is present but unusable is never downgraded to an anonymous request. - `403`: Authenticated but not authorized. Either the acting user lacks the required resource permission, the key's scope ceiling excludes it, or the endpoint rejects this credential type (`CREDENTIAL_NOT_PERMITTED`). - `404`: The resource does not exist in the parent named by the path, or is hidden from the caller. Absence and privacy denial are deliberately indistinguishable so project, organization, and private-team existence cannot be probed. - `429`: Request rate exceeded, either globally or for this key. - `500`: Unexpected server error. ## Changes - **2026-10-28** (v2) `0230867823db`: 2 breaking, 2 info - removed the required property `evidence/usage/groups/items/allOf[#/components/schemas/UsageTotals]/credits` from the response with the `200` status - removed the required property `evidence/usage/totals/credits` from the response with the `200` status - added the required property `evidence/usage/groups/items/allOf[#/components/schemas/UsageTotals]/amountUsd` to the response with the `200` status - added the required property `evidence/usage/totals/amountUsd` to the response with the `200` status - **2026-09-15** (v2) `67c8b8616dbb`: 5 info - the `success` response property const value `false` was added for the status `401` - the `success` response property const value `false` was added for the status `403` - the `success` response property const value `false` was added for the status `404` - the `success` response property const value `false` was added for the status `429` - …1 more - **2026-09-15** (v2) `48948af37797`: 1 info - endpoint added [Operation history](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/changes/api/v2/evaluation-runs/:runId/get.md) --- [API](https://skmtc.dev/celedon-solutions/apis/davinci-public-api.md) - [All operations](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/revisions/279218ca2e8d?raw)