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

# Background Responses

> Run a Responses API request asynchronously and retrieve the result by response ID.

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](/reference/ai-router/responses/v3-create-response) 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.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  response=$(curl -sS -X POST https://api.orq.ai/v3/router/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o-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://api.orq.ai/v3/router/responses/$response_id" \
      -H "Authorization: Bearer $ORQ_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['ORQ_API_KEY']}`,
    'Content-Type': 'application/json',
  };

  let response = await fetch('https://api.orq.ai/v3/router/responses', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      model: 'openai/gpt-4o-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://api.orq.ai/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('ORQ_API_KEY', '')}",
      'Content-Type': 'application/json',
  }

  response = requests.post(
      'https://api.orq.ai/v3/router/responses',
      headers=headers,
      json={
          'model': 'openai/gpt-4o-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://api.orq.ai/v3/router/responses/{response['id']}",
          headers=headers,
      ).json()

  print(response)
  ```
</CodeGroup>

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

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