# Cancel a response

`POST https://api.azta.ai/v1/responses/{response_id}/cancel`

Stop a response. A dropped stream cancels nothing; this call does.

The response comes back `cancelled` once nothing was left running, or `in_progress` while a step is still being torn down; a second cancel then also answers `200`. A response that has already finished is `response_finished`, which includes one whose answer was complete when the cancel arrived: that one completes and is charged.

A response cancelled before its first text delta reached you is free; one cancelled after it is charged. The call accepts `Idempotency-Key` and stores nothing.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `response_id` | path | yes | The `id` of a response of this key. |
| `Idempotency-Key` | header | no | Makes a retry safe. A repeat of the same request answers with the stored result and `Idempotent-Replayed: true`, and is never charged again; the same key on a different request is `idempotency_key_reused`. Without it, a retry is a new, charged request. |

## Responses

### 200

The response after the cancel.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | integer or null | yes | Unix seconds at which the response ended, whatever its status. |
| `created_at` | integer | yes | Unix seconds. |
| `depth` | string (`standard`, `deep`) or null | yes | Echoed from the request; null for a response made before depth existed. |
| `error` | object or null | yes |  |
| `id` | string | yes |  |
| `incomplete_details` | object or null | yes |  |
| `instructions` | string or null | yes |  |
| `metadata` | object | yes |  |
| `model` | string | yes | The label the request named, echoed. |
| `object` | string (`response`) | yes |  |
| `output` | array of object | yes | Empty until the response is `completed`: there is no partial text. |
| `output[].content` | array of object | yes |  |
| `output[].content[].annotations` | array of object | yes |  |
| `output[].content[].annotations[].end_index` | integer | yes | Where the label ends, exclusive. |
| `output[].content[].annotations[].source_number` | integer | yes | The `number` of the source in `sources`. |
| `output[].content[].annotations[].start_index` | integer | yes | Where the label starts, counted in Unicode code points of `text`, so `text[start_index:end_index]` is the label. |
| `output[].content[].annotations[].title` | string | yes |  |
| `output[].content[].annotations[].type` | string (`url_citation`) | yes |  |
| `output[].content[].annotations[].url` | string | yes |  |
| `output[].content[].text` | string | yes |  |
| `output[].content[].type` | string (`output_text`) | yes |  |
| `output[].id` | string | yes |  |
| `output[].role` | string (`assistant`) | yes |  |
| `output[].status` | string (`completed`) | yes |  |
| `output[].type` | string (`message`) | yes |  |
| `parallel_tool_calls` | boolean | yes |  |
| `previous_response_id` | string or null | yes |  |
| `reasoning` | object | yes |  |
| `reasoning.effort` | string or null | yes |  |
| `reasoning.summary` | string or null | yes |  |
| `sources` | array of object | yes | What the answer cites, numbered by first citation. Empty until the response is `completed`. |
| `sources[].act` | object or null | yes |  |
| `sources[].country` | string or null | yes | A lower-case country code. |
| `sources[].excerpt` | string or null | yes | At most 300 characters, whitespace collapsed. |
| `sources[].kind` | string (`provision`, `passage`, `web`) | yes |  |
| `sources[].number` | integer | yes | `source_number` of the annotations that cite it. |
| `sources[].section` | string or null | yes |  |
| `sources[].title` | string | yes | A display label: the act's short title, then the section. |
| `sources[].unit_id` | string or null | yes | A provision's id, the same across versions and re-ingestion: pass it to `POST /v1/provisions/fetch`. A Hungarian id is `hu:njt:<njt id>:<path>`. Null for a passage, a web page, and a provision whose id is not stable. |
| `sources[].url` | string | yes | An absolute URL, always present. |
| `sources[].url_kind` | string (`official`, `viewer`, `web`) | yes | `official` is the publisher's own page, `viewer` our provision or document viewer, `web` a web page's own URL. |
| `sources[].version` | object or null | yes | The version cited. Null for a passage, a web page and a version that never commenced. |
| `status` | string (`queued`, `in_progress`, `completed`, `failed`, `cancelled`) | yes |  |
| `store` | boolean | yes |  |
| `temperature` | number | yes |  |
| `text` | object | yes |  |
| `text.format` | object | yes |  |
| `text.format.type` | string (`text`) | yes |  |
| `tool_choice` | string | yes |  |
| `tools` | array of object | yes |  |
| `top_p` | number | yes |  |
| `truncation` | string (`auto`, `disabled`) | yes |  |
| `usage` | object or null | yes | Present once the response has ended. |

### 401

The request was refused.

- `invalid_api_key`: The key is missing, malformed, unknown, revoked or expired.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 404

The request was refused.

- `not_found`: No such response: the id is unknown or malformed, or the response belongs to another key.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 409

The request was refused.

- `response_finished`: The response has already finished.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |

### 500

The request was refused.

- `server_error`: Anything else. It never carries exception text.

Content type: `application/json`.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | object | yes | What a refused request says. Branch on `code`; `message` is English and names no internal detail. |
| `error.code` | string (`invalid_request`, `unsupported_parameter`, `unsupported_jurisdiction`, `idempotency_key_reused`, `invalid_api_key`, `insufficient_credits`, `spend_cap_reached`, `account_suspended`, `not_found`, `idempotency_key_in_use`, `response_finished`, `rate_limit_exceeded`, `concurrency_limit_exceeded`, `server_error`, `ledger_unavailable`) | yes |  |
| `error.message` | string | yes |  |
| `error.param` | string or null | yes | The field or header at fault, or null when no one is. |
| `error.type` | string (`invalid_request_error`, `authentication_error`, `billing_error`, `permission_error`, `not_found_error`, `rate_limit_error`, `server_error`) | yes |  |