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

# Background Responses

> Run a Responses API request asynchronously with background mode on the AI Gateway and poll the response ID until processing completes.

Use background execution when a **Responses API** request should return before model execution completes. Set `background` to `true` on `POST /v3/router/responses`. The **AI Gateway** stores the response, returns its ID with `status: "queued"`, and processes it asynchronously.

Poll `GET /v3/router/responses/{response_id}` with the same ID until the response reaches a terminal status. See the [Responses API reference](/docs/reference/responses/create-response.md) for the complete request and response schema.

## Quick start

The following examples submit a background response, then poll until processing finishes. Set `store` to `true`; background responses require stored responses.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
response=$(curl -sS -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Summarize the background response workflow in one sentence.",
    "background": true,
    "store": true
  }')

response_id=$(printf '%s' "$response" | jq -r '.id')
status=$(printf '%s' "$response" | jq -r '.status')

while [ "$status" = "queued" ] || [ "$status" = "in_progress" ]; do
  sleep 1
  response=$(curl -sS "https://router.toqan.ai/eu/v3/router/responses/$response_id" \
    -H "Authorization: Bearer $TOQAN_API_KEY")
  status=$(printf '%s' "$response" | jq -r '.status')
done

printf '%s\n' "$response"
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const headers = {
  Authorization: `Bearer ${process.env['TOQAN_API_KEY']}`,
  'Content-Type': 'application/json',
};

let response = await fetch('https://router.toqan.ai/eu/v3/router/responses', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    model: 'openai/gpt-5.4-mini',
    input: 'Summarize the background response workflow in one sentence.',
    background: true,
    store: true,
  }),
}).then((result) => result.json());

while (response.status === 'queued' || response.status === 'in_progress') {
  await new Promise((resolve) => setTimeout(resolve, 1000));
  response = await fetch(
    `https://router.toqan.ai/eu/v3/router/responses/${response.id}`,
    { headers },
  ).then((result) => result.json());
}

console.log(response);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import os
import time
import requests

headers = {
    'Authorization': f"Bearer {os.getenv('TOQAN_API_KEY', '')}",
    'Content-Type': 'application/json',
}

response = requests.post(
    'https://router.toqan.ai/eu/v3/router/responses',
    headers=headers,
    json={
        'model': 'openai/gpt-5.4-mini',
        'input': 'Summarize the background response workflow in one sentence.',
        'background': True,
        'store': True,
    },
).json()

while response['status'] in ('queued', 'in_progress'):
    time.sleep(1)
    response = requests.get(
        f"https://router.toqan.ai/eu/v3/router/responses/{response['id']}",
        headers=headers,
    ).json()

print(response)
```

## Response lifecycle

The create request returns the response object with a stable `id`. Retrieve that same object while it progresses through the following statuses:

| Status | Meaning |
| - | - |
| `queued` | The request was accepted and is waiting for background execution. |
| `in_progress` | Background execution is running. |
| `completed` | The response contains the completed output. |
| `failed` | Execution stopped with an error in the `error` field. |
| `incomplete` | Execution ended without a completed response; inspect `incomplete_details`. |

Completed responses include `output` and `completed_at`. Failed responses retain the response ID so the error can be retrieved with the same GET request.

## Runtime limit and polling

Background execution stops after 30 minutes. The limit covers the whole run and overrides any `max_execution_time` in `limits` or on the agent. A run stopped by it ends as `failed` with the reason in `error`, or as `incomplete` with `incomplete_details.reason: "max_time"` when the limit is reached between model calls.

No fixed polling interval is required. The Quick start polls every second; a slower interval works for long runs. Stop at `completed`, `failed` or `incomplete`.

## Cancelling

Background responses cannot be cancelled: `/v3/router/responses/{response_id}` serves `GET` only. Stopping the polling loop does not stop the run, which continues to a terminal status and stays retrievable.

## Configuration and limitations

| Field | Requirement |
| - | - |
| `background` | Set to `true` to enqueue the response and return immediately. |
| `store` | Omit this field or set it to `true`. `store: false` is rejected for background responses. |
| `stream` | Omit this field or set it to `false`. Background execution cannot be combined with streaming. |

Background execution uses the standard Responses API model, input, tools, and response schema. The asynchronous behavior changes when the result becomes available, not the shape of the final response.

> [!NOTE]
>
> For many offline requests, submit a [batch](/docs/ai-gateway/features/batches.md) instead. Background execution covers a single long-running response.


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