# Cancel a test run (/docs/api/voice-agents/agent-tests/cancelAgentTestRun)

> For the complete documentation index, see [llms.txt](https://docs.tandemcx.ai/llms.txt). Any page on this site can be fetched as Markdown by appending `.md` to its URL.

`POST /v1/agent-media/agents/{agentId}/test-runs/{runId}/cancel`

Cancel a test run

Mark an active run `cancelled`. A case in progress stops before its next turn and records no result. A case already past its last turn (being judged, or whose last turn ended the conversation or handed it off) may still record one. Results already recorded are kept.

## Request

**Base URL:** `https://api.tandemcx.ai`

**Authentication:** `Authorization: Bearer <token>` — A Tandem bearer token. Requests are scoped to the organization the token belongs to; no organization header is required.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agentId` | string | Yes | The agent's unique ID. |
| `runId` | string | Yes | The test run's unique ID. |

## Responses

### 200 — The cancelled run.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `run` | object | No | — |
| `run.runId` | string | No | — |
| `run.agentId` | string | No | — |
| `run.version` | string | No | — |
| `run.configHash` | string | No | SHA-256 of the version's configuration when the run started. A version whose current hash differs was edited since. |
| `run.testIds` | array of string | No | — |
| `run.repeats` | object | No | Attempts queued per test id. Invalid tests are absent. |
| `run.status` | enum: `queued` \| `running` \| `passed` \| `failed` \| `errored` \| `cancelled` | No | A finished run is `failed` when any case failed, else `errored` when any case errored, else `passed`. `invalid` cases never fail a run. |
| `run.counts` | object | No | Cases, where a case is one attempt of one test. |
| `run.counts.total` | integer | No | — |
| `run.counts.done` | integer | No | — |
| `run.counts.pass` | integer | No | — |
| `run.counts.fail` | integer | No | — |
| `run.counts.error` | integer | No | — |
| `run.counts.invalid` | integer | No | — |
| `run.usage` | object | No | — |
| `run.usage.inputTokens` | integer | No | — |
| `run.usage.outputTokens` | integer | No | — |
| `run.simulatorModelId` | string | No | The Bedrock model id the run's simulated caller uses. |
| `run.judgeModelId` | string | No | The Bedrock model id the run's judge uses. |
| `run.agentTemperature` | number | No | — |
| `run.triggeredBy` | object | No | — |
| `run.triggeredBy.kind` | enum: `user` \| `sparky` | No | — |
| `run.triggeredBy.userId` | string | No | — |
| `run.createdAt` | string (date-time) | No | — |
| `run.finishedAt` | string (date-time) | No | — |
| `run.ttl` | integer | No | Epoch seconds when the run expires, 90 days after it started. |

### 400 — The request was malformed. `error` names the reason, such as `invalid_agentId`, `invalid_version`, `invalid_slot`, or `invalid_prompt`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | string | No | A stable machine-readable code. |
| `message` | string | No | A human-readable explanation, safe to show to an end user. Present on errors an operator can act on; browser clients display this field in preference to a generic fallback. |
| `limit` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the bound itself. |
| `length` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the measured size of the rejected value. |
| `reason` | string | No | Present on some errors (e.g. `invalid_avatar_image`) that have more than one cause: which one applied. |

### 401 — Missing, malformed, or expired bearer token.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | string | No | A stable machine-readable code. |
| `message` | string | No | A human-readable explanation, safe to show to an end user. Present on errors an operator can act on; browser clients display this field in preference to a generic fallback. |
| `limit` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the bound itself. |
| `length` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the measured size of the rejected value. |
| `reason` | string | No | Present on some errors (e.g. `invalid_avatar_image`) that have more than one cause: which one applied. |

### 404 — `error` is `not_found`: the resource does not exist.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | string | No | A stable machine-readable code. |
| `message` | string | No | A human-readable explanation, safe to show to an end user. Present on errors an operator can act on; browser clients display this field in preference to a generic fallback. |
| `limit` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the bound itself. |
| `length` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the measured size of the rejected value. |
| `reason` | string | No | Present on some errors (e.g. `invalid_avatar_image`) that have more than one cause: which one applied. |

### 409 — `error` is `run_finished`: the run is no longer `queued` or `running`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | string | No | A stable machine-readable code. |
| `message` | string | No | A human-readable explanation, safe to show to an end user. Present on errors an operator can act on; browser clients display this field in preference to a generic fallback. |
| `limit` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the bound itself. |
| `length` | integer | No | Present on some errors (e.g. `prompt_too_long`) that reject a value against a fixed bound: the measured size of the rejected value. |
| `reason` | string | No | Present on some errors (e.g. `invalid_avatar_image`) that have more than one cause: which one applied. |