--- title: "Clean up an evaluation sandbox" method: DELETE path: "/api/v2/evaluation-runs/{runId}" tags: ["Evaluations"] --- # Clean up an evaluation sandbox `DELETE /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 Idempotently stops target work, revokes target grants, releases the sandbox pin, and deletes the ephemeral project. Cleanup state is retained as evidence; a cleanup error never hides the run's primary failure. ## Response `200` Cleanup completed or had already completed. - 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 - `202`: Cleanup has been requested and is still running. - `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`: 4 breaking, 4 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/groups/items/allOf[#/components/schemas/UsageTotals]/credits` from the response with the `202` status - removed the required property `evidence/usage/totals/credits` from the response with the `200` status - removed the required property `evidence/usage/totals/credits` from the response with the `202` status - …4 more - **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/delete.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)