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 for the complete request and response schema.
Quick start
The following examples submit a background response, then poll until processing finishes. Background responses are stored: omitstore or set it to true.
Response lifecycle
The create request returns the response object with a stableid. Retrieve that same object while it progresses through the following statuses:
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 (1800 seconds). The limit covers the whole run and overrides anymax_execution_time in limits or on the agent; the other run limits still apply, and Run Limits lists their defaults. 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
Two combinations fail with
400 invalid_request: background: true with store: false returns the message responses.background_requires_store, and background: true with stream: true returns responses.background_stream_conflict.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.
For many offline requests, submit a batch instead. Background execution covers a single long-running response.