> ## 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.

# Get Response

> Retrieve a response by ID.

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

```json 200 theme={null}
{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1699000000,
  "model": "gpt-4",
  "status": "completed",
  "conversation": { "id": "conv_9f2c1d7b4a6e08f35c1d2b7e4a9f6038" },
  "previous_response_id": null,
  "output": [
    {
      "id": "msg_xyz",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "The capital of France is Paris.", "annotations": [] }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 8,
    "total_tokens": 23
  },
  "metadata": null
}
```

## 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 retrieve |

## The id resolves from the moment the run starts

A response id is retrievable for the **whole life of the run**, not only once it finishes. A
`GET` issued while the run is still working returns the envelope with `status: "in_progress"`
and an empty `output` — for a background run, for a streaming run, and for an ordinary
synchronous one.

```json theme={null}
{
  "id": "resp_abc123",
  "object": "response",
  "status": "in_progress",
  "created_at": 1699000000,
  "conversation": { "id": "conv_9f2c…" },
  "output": [],
  "usage": null
}
```

That makes the id you receive in `response.created` (the first frame of a stream) usable
immediately — to poll, to show the run in an operator view, or to
[cancel](https://docs.budecosystem.com/api-sdk/responses/cancel-response.md) it.

> [!NOTE]
>
> A paused approval also reports `status: "in_progress"`; what identifies it is an
> `mcp_approval_request` item in `output`. See
> [Governance outcomes](https://docs.budecosystem.com/api-sdk/responses/response-format.md#governance-outcomes).

## When a response stops being retrievable

| Cause | Result |
| - | - |
| The request set `store: false` | `404` once the answer has been returned — see [what that guarantees](https://docs.budecosystem.com/api-sdk/responses/create-response.md#what-store-false-guarantees). |
| The response was deleted | `404`. Deleting one turn does not remove the rest of its thread. |
| Retention window elapsed | `404`. Responses in a **terminal** state (`completed`, `failed`, `incomplete`, `cancelled`) are deleted after `RUN_RETENTION_DAYS` — 30 days by default, configurable per installation. |

Runs that are **not** terminal — including one paused awaiting a human approval — are never
collected by retention at any age, so a pending approval cannot expire out from under the
client that is waiting on it.

## Supported Providers

`GET /v1/responses/{id}` is **provider-agnostic** — every response Bud stores is retrievable
this way, whichever model produced it.

> [!NOTE]
>
> Retrieval is scoped to the API key that created the response: another key asking for the same
> id gets `404`, never another tenant's content.


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