OpenAI has added two new completion windows to background mode in the Responses API. If a request can wait up to two or eight hours for its first answer, you now pay noticeably less per token: the official background mode guide lists 30% below Standard for the 2h window and 40% below Standard for 8h. The feature is in public beta.
This tutorial explains when the discounted windows make sense, what rules a request must follow to qualify, and how to wire it up in Python with polling, webhooks and multi-step agent runs.
What changed
Background mode already let you start a long Responses API request, get a response ID back immediately and fetch the result later. The new background_options.completion_window setting adds a choice about how soon you need that result:
| Window | Typical use (from the docs) | Token discount |
|---|---|---|
soonest (default) |
An on-demand report while someone waits | None |
2h |
Analyse the morning’s support tickets before an afternoon meeting | 30% below Standard |
8h |
Review a batch of documents overnight | 40% below Standard |
For 2h and 8h, the API targets completion within the selected window after it accepts the request. It is a target, not a hard deadline, so design your app to handle a late or failed result.
Supported models
According to the guide, discounted windows are in public beta on GPT-6.2 Astra, GPT-6.2 Sol, GPT-6.1 Terra and GPT-6 Luna. OpenAI also notes that, starting with GPT-6.2 Astra and Sol, new models launch without Flex processing (service_tier: "flex"). For long-running work on those models, completion windows are the intended replacement.
The rules a request must follow
A request only gets the discount if it meets all of these conditions:
backgroundistrue.background_options.completion_windowis"2h"or"8h".streamis unset orfalse. Streaming only works with the defaultsoonestwindow.- Standard processing is used. Set
service_tierto"default". With"auto", the request qualifies only if the API happens to select Standard.
Two more details matter in production:
- Rate limits.
2hand8hrequests share the Batch/Background rate limit with Batch API jobs, and input tokens are counted at submission. Requests usingsoonestuse your normal limits. - Prompt caching. Standard requests outside the discounted windows can’t reuse prompt cache entries created by
2hor8hrequests, even when the prompt is identical.
Background mode also stores response data temporarily, even when store is false or you use Zero Data Retention. The guide says this data is encrypted at rest for all windows. Check this against your data-handling policy before you send sensitive documents.
Setup
Install or upgrade the official SDK and set your key:
pip install --upgrade openai
export OPENAI_API_KEY="sk-..."
The examples below pass background_options through extra_body. That works whether or not your installed SDK version has a typed parameter for it yet. If your SDK version does expose background_options as a keyword argument, you can pass it directly instead.
Example 1: an overnight document review
from openai import OpenAI
client = OpenAI()
with open("contracts_batch.txt", encoding="utf-8") as f:
documents = f.read()
resp = client.responses.create(
model="gpt-6.1-terra",
input=(
"Review these contracts. For each one, list missing approvals "
"and any clause that needs legal review.\n\n" + documents
),
background=True,
service_tier="default", # Standard processing is required
extra_body={
"background_options": {"completion_window": "8h"}
},
)
print(resp.id, resp.status) # save the ID somewhere durable
Save resp.id in your database or job queue. You will need it to fetch the result later.
Example 2: polling for the result
If you can’t receive webhooks, poll the response by ID. Keep the interval long; there’s no point checking every second for an eight-hour job.
import time
from openai import OpenAI
client = OpenAI()
def wait_for(response_id: str, every: int = 300):
while True:
r = client.responses.retrieve(response_id)
if r.status in ("queued", "in_progress"):
time.sleep(every)
continue
return r
result = wait_for("resp_...")
if result.status == "completed":
print(result.output_text)
else:
print("Finished with status:", result.status)
The guide notes that after the API accepts a 2h or 8h request, it automatically retries eligible capacity errors while the response is queued or in_progress. You just keep waiting on the same ID.
Example 3: webhooks instead of polling
Polling works, but webhooks are cleaner. Create a webhook endpoint for the project that sends your background requests and subscribe to response.completed (plus the failed, incomplete and cancelled events you care about). OpenAI’s advice is to verify the signature, hand longer work to a background worker, and return a 2xx quickly.
# Flask example
from flask import Flask, request
from openai import OpenAI
app = Flask(__name__)
client = OpenAI() # reads OPENAI_WEBHOOK_SECRET for verification
@app.post("/openai/webhook")
def openai_webhook():
event = client.webhooks.unwrap(request.get_data(), request.headers)
if event.type == "response.completed":
enqueue_result_job(event.data.id) # your own queue function
return "", 200
Webhook deliveries can repeat, so de-duplicate them using the webhook-id header before you process an event twice.
Example 4: a multi-step agent run
Completion windows also work for agent loops where the model calls a tool and you send the result back. To make follow-up requests eligible for higher queue priority, reuse the same window, model, project and a continuation_id that your application chooses.
RUN_ID = "contract-review-2026-11-21"
tools = [{
"type": "function",
"name": "get_document",
"description": "Fetch a contract by ID",
"parameters": {
"type": "object",
"properties": {"doc_id": {"type": "string"}},
"required": ["doc_id"],
},
}]
first = client.responses.create(
model="gpt-6.1-terra",
input="Check contract C-1042 for missing approvals.",
tools=tools,
background=True,
service_tier="default",
extra_body={"background_options": {
"completion_window": "8h",
"continuation_id": RUN_ID,
}},
)
When the first response completes and contains a function_call item, run your tool and send a follow-up with the same model, service tier, background setting, window and continuation ID:
done = wait_for(first.id) # or react to the webhook
call = next(i for i in done.output if i.type == "function_call")
doc_text = load_document("C-1042") # your own function
follow_up = client.responses.create(
model="gpt-6.1-terra",
previous_response_id=done.id,
input=[{
"type": "function_call_output",
"call_id": call.call_id,
"output": doc_text,
}],
tools=tools,
background=True,
service_tier="default",
extra_body={"background_options": {
"completion_window": "8h",
"continuation_id": RUN_ID,
}},
)
The discount applies to model token rates on each eligible request, including follow-ups. If the earlier response has expired by the time you continue, omit previous_response_id and replay the original input plus every saved output item in order, then append your function_call_output. That means you should save the full output while you can still retrieve it.
When to use which window
- Use
soonestfor anything a user is actively waiting for, or when you need streaming. - Use
2hfor same-day internal jobs: ticket triage, daily summaries, code review digests. - Use
8hfor overnight work: document reviews, data enrichment, backlog classification. - Use the Batch API when you have many independent requests you can submit together up front. Background mode with completion windows is the better fit for agent runs where each step depends on the previous one.
Key takeaways
- Set
background=True,service_tier="default"andbackground_options.completion_windowto"2h"or"8h"to get 30% or 40% off Standard token rates. - Don’t stream, and remember that these requests share the Batch/Background rate limit.
- Reuse a
continuation_idacross follow-up requests in an agent run for higher queue priority. - The feature is in public beta on four models, so check the background mode guide and pricing page before you move production traffic.
