> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budecosystem.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Response

> Stop an in-progress response — a background run, or a stream in flight.

```bash cURL theme={null}
curl -X POST https://gateway.bud.studio/v1/responses/resp_abc123/cancel \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-model-name: gpt-4"
```

```json 200 theme={null}
{
  "id": "resp_abc123",
  "object": "response",
  "status": "cancelled",
  "created_at": 1699000000,
  "cancelled_at": 1699000030,
  "conversation": { "id": "conv_9f2c1d7b4a6e08f35c1d2b7e4a9f6038" },
  "output": [
    {
      "id": "msg_xyz",
      "type": "message",
      "role": "assistant",
      "status": "in_progress",
      "content": [
        { "type": "output_text", "text": "The capital of Fra", "annotations": [] }
      ]
    }
  ]
}
```

## Headers

| Parameter | Type | Required | Description |
| - | - | - | - |
| Authorization | string | Yes | Bearer authentication header |
| x-model-name | string | No | Model name for routing. Default: gpt-4-responses |

## Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| response\_id | string | Yes | The ID of the response to cancel |

## What can be cancelled

| The response is… | Result |
| - | - |
| a **background** run (`background: true`), still working | `200` — the run is stopped and the envelope comes back `cancelled`. |
| a **streaming** run, still in flight | `200` — the stream is ended (see below) and the model call is stopped so it stops billing. |
| an ordinary **non-streaming** run | `409 cannot_cancel_non_background` — there is nothing to interrupt: the result is returned to the request that is waiting for it. |
| already `cancelled` | `200`, idempotent — the existing envelope. A client cannot tell whether its cancel raced the stream's own ending, so answering beats an error. |
| a **background** run, already `completed` / `failed` / `incomplete` | `200`, idempotent — the existing envelope. |
| a **non-streaming** run, already `completed` / `failed` / `incomplete` | `409 cannot_cancel_non_background`. |
| unknown, or owned by another API key | `404`. |

The id is cancellable **from the moment the run starts** — including the id in the
`response.created` frame, the first thing a stream sends.

```json 409 theme={null}
{
  "error": {
    "message": "This response is not streaming, so there is nothing to interrupt: a synchronous result is returned to the request waiting for it. Only a streaming or a background response can be cancelled.",
    "type": "invalid_request_error",
    "code": "cannot_cancel_non_background"
  }
}
```

## What the streaming client sees

The stream ends **within one chunk** of the cancel — the client keeps every byte the model had
already produced — and the last frame it receives is:

```
event: response.incomplete
data: {"type":"response.incomplete","sequence_number":42,"response":{"id":"resp_abc123","status":"cancelled", ...}}
```

The event type is `response.incomplete` because OpenAI's stream-event union has no
`response.cancelled` member; the response object it carries says `cancelled`, which is what a
later `GET /v1/responses/{id}` reports too — so the stream and the stored response never
disagree about how the run ended.

A cancel that arrives **after** the stream has already sent its terminal frame changes nothing
about the answer: no second terminal frame is emitted, and the output that was delivered stays
on the stored response.

> [!NOTE]
>
> Cancel works across replicas. A cancel served by a different pod than the one driving the
> stream is picked up from the stored response's status within about two seconds, so the caller
> does not need to reach a particular instance.

## What is kept

A cancelled run keeps what it had produced: the partial output that was streamed to the client
is stored on the response rather than being discarded, so `GET /v1/responses/{id}` returns
`status: "cancelled"` alongside the tokens that were actually delivered.

## Supported Providers

Cancellation is **provider-agnostic** — it applies to any background or streaming response Bud
is driving, whichever model is behind it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.