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:

  1. background is true.
  2. background_options.completion_window is "2h" or "8h".
  3. stream is unset or false. Streaming only works with the default soonest window.
  4. Standard processing is used. Set service_tier to "default". With "auto", the request qualifies only if the API happens to select Standard.

Two more details matter in production:

  • Rate limits. 2h and 8h requests share the Batch/Background rate limit with Batch API jobs, and input tokens are counted at submission. Requests using soonest use your normal limits.
  • Prompt caching. Standard requests outside the discounted windows can’t reuse prompt cache entries created by 2h or 8h requests, 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 soonest for anything a user is actively waiting for, or when you need streaming.
  • Use 2h for same-day internal jobs: ticket triage, daily summaries, code review digests.
  • Use 8h for 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" and background_options.completion_window to "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_id across 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.