For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

Background mode

Run long-running Responses API requests and multi-turn workflows asynchronously.

Use background mode to run long-running Responses API requests asynchronously, including multi-step agent runs. An agent run is the full workflow your application manages: it sends an initial request and can use the result to decide what to do next, such as running a tool and sending its output in a follow-up request. For independent requests you can submit together up front, use the Batch API.

Choose a completion window

Set background_options.completion_window based on how soon you need the initial response. For 2h and 8h, the API targets completion within the selected window after it accepts the request.

Window When to use it Model token discount
soonest (default) Generate an on-demand report while someone waits for the result. None
2h Analyze the morning’s support tickets before an afternoon triage meeting. 30% below Standard
8h Review a batch of documents overnight for the next morning. 40% below Standard

For an overnight document review, start with an 8h request. If the first response asks your application to look up a document, run the tool and send its result in a follow-up request. Reuse the window, continuation ID, model, and project to qualify for higher queue priority.

The completion target starts when the API accepts the initial request and applies to that response. The discount applies to model token rates on each eligible request, including follow-ups. In this example, both requests qualify for the 40% discount.

Start a background request

Set background to true and save the response ID returned by the API. Use a webhook to learn when the request finishes and retrieve the response by ID. This example uses the default completion window (soonest).

Generate a response in the background
from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-6.2-astra",
    input="Write a very long novel about otters in space.",
    background=True,
)

print(resp.status)

Background mode temporarily stores response data even when you set store to false or use Zero Data Retention. The API uses this data to run the request and make the result available for retrieval. The API encrypts temporarily stored request content at rest for all completion windows (soonest, 2h, and 8h). See Data controls for details on temporary storage.

Receive results with webhooks

  1. Create a webhook endpoint for the project that sends your background requests. Subscribe to response.completed and to the events for failed, incomplete, or canceled responses you want to handle.
  2. Verify the signature on incoming events. Hand off any longer work to a background worker and return a 2xx response as soon as you accept the event.
  3. For response.completed, use event.data.id to retrieve the response. Handle other terminal events according to your application’s workflow.

The webhooks guide includes a server example that verifies the signature and retrieves the completed response. If you can’t receive webhooks, poll the response using its ID.

After the API accepts a 2h or 8h request, it automatically retries eligible capacity errors. While the response is queued or in_progress, wait for a webhook or poll using the same response ID.

Use discounted completion windows

Discounted completion windows are in public beta on GPT-6.2 Astra, GPT-6.2 Sol, GPT-6.1 Terra, and GPT-6 Luna.

Requests with 2h or 8h completion windows share the Batch/Background Rate Limit with Batch API jobs. The API counts input tokens at submission. Requests with the default soonest window use the regular request and token limits.

If your application can wait for the initial response, use a two-hour or eight-hour completion window. Set background to true and set background_options.completion_window to 2h or 8h. Leave stream unset or set it to false. See completion window pricing.

Discounted windows require Standard processing. Set service_tier to default to select Standard. With auto, the request qualifies only if the API selects Standard.

Standard requests outside the discounted completion windows can’t reuse prompt cache entries created by 2h or 8h background requests, even when the prompt is identical.

For a single overnight document review, send an 8h request to POST /v1/responses with gpt-6.1-terra and the document contents in input. Leave background_options.continuation_id unset if you only need one response.

For the default completion window, omit background_options.completion_window or set it to soonest.

Run a workflow with follow-up requests

Use the same API project for both requests in the overnight document review.

  1. Ask gpt-6.1-terra to look up a document by ID and review it for missing approvals in a create response request. Set background to true, service_tier to default, and background_options.completion_window to 8h. Set background_options.continuation_id to a unique ID your application chooses for this run. Include a function tool that retrieves a document by ID. Save the response ID returned by the API.
  2. When you receive a response.completed webhook, deduplicate deliveries using the webhook-id header. Check that event.data.id matches the saved response ID before proceeding. Retrieve the response and run the document lookup requested by its function_call output item. If your app may need to continue after the response expires, save the original input and the full response output while you can still retrieve it.
  3. Create a follow-up response with the same model, service tier, background setting, completion window, and continuation ID. Set previous_response_id to event.data.id to carry forward conversation history if the prior response is still available. In input, send a function_call_output item with the original function call’s call_id and the retrieved document as its output.

Reuse continuation_id to make follow-ups eligible for higher queue priority. Start times depend on scheduling. If the prior response expires, omit previous_response_id and pass the conversation history in input. Replay the original input and every item in the saved response output in order, including any encrypted reasoning items and the original function call. Then append the new function_call_output item.

Polling background responses

As an alternative to webhooks, use the response ID to check the request’s status with the retrieve endpoint. Keep polling while the status is queued or in_progress. When the status changes to a terminal state, stop polling.

Retrieve a response executing in the background
from openai import OpenAI
from time import sleep

client = OpenAI()

resp = client.responses.create(
    model="gpt-6.2-astra",
    input="Write a very long novel about otters in space.",
    background=True,
)

while resp.status in {"queued", "in_progress"}:
    print(f"Current status: {resp.status}")
    sleep(2)
    resp = client.responses.retrieve(resp.id)

print(f"Final status: {resp.status}\nOutput:\n{resp.output_text}")

Cancelling a background response

You can also cancel an in-flight response like this:

Cancel an ongoing response
import os

from openai import OpenAI

response_id = os.environ["OPENAI_RESPONSE_ID"]
client = OpenAI()

resp = client.responses.cancel(response_id)

print(resp.status)

Canceling twice is idempotent. Later calls return the final Response object. For a synchronous response, close the connection instead.

Streaming a background response

To stream a background response, use the default completion window (soonest) and set stream: true when you create it. For 2h and 8h requests, omit stream or set it to false.

If the connection drops, resume the stream by passing the last event’s sequence_number as starting_after. You can’t stream a response later if it was created without streaming.

Time to first token can be higher for a background response than for a synchronous response.

Generate and stream a background response
curl https://api.openai.com/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
  "model": "gpt-6.2-astra",
  "input": "Write a very long novel about otters in space.",
  "background": true,
  "stream": true
}'

# To resume:
curl "https://api.openai.com/v1/responses/resp_123?stream=true&starting_after=42" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OPENAI_API_KEY"