OpenAI Responses API Guide: Background Runs and Context Management

InYourLeague Research · 2026-08-31

Answer in brief

Use the CLI’s optional --background control for background execution, and treat --context-management and --conversation as separate documented controls with different stated purposes. The supplied excerpt does not define raw HTTP field spelling for --context-management, tool-selection modes, polling intervals, lifecycle states, retry behavior, or recovery guarantees, so those details must be verified in the relevant full operation contracts.

Key facts at a glance

Failure modes and verification

FAQ

What does --background do?

In the supplied CLI reference, --background is an optional boolean that controls whether the model response runs in the background. The excerpt does not specify completion timing, lifecycle states, or durability guarantees.

Can --context-management be copied directly into an HTTP JSON body?

That is not established. --context-management is the CLI spelling shown in the excerpt, while the corresponding raw JSON property name is not supplied. Check the complete HTTP or SDK schema before constructing the request.

Are --context-management and --conversation alternatives?

The excerpt documents both as optional controls but does not say that they are mutually exclusive, interchangeable, or restricted to one per request. Use each for its documented purpose and verify combined use against the complete contract.

What continuity does --conversation provide?

Existing conversation items are prepended to the response input. After completion, that response’s input and output items are automatically added to the conversation, according to the supplied official reference.

How can a response choose a tool?

The excerpt says a response may call custom code or use built-in tools such as web search and file search. It does not define configuration syntax, automatic selection, forced selection, or required-tool behavior.

How should a client poll a background response?

Retrieve a response appears in the reference navigation, making retrieval a reasonable polling candidate rather than a documented polling procedure. Review its full contract for lookup inputs, statuses, terminal outcomes, and errors, then define cadence, backoff, and timeouts as client policies.

How should interrupted long-running work be recovered?

Keep a durable application job record. If the full Retrieve contract confirms an appropriate lookup mechanism, check the existing work before creating a replacement and add client-side duplicate protection when needed. The excerpt does not promise automatic resumption or deduplication.

Sources and freshness

• Official source
• Last verified: 2026-08-31

Extended guide

Direct answer

The supplied evidence is the CLI-form reference for openai responses create, which maps to POST /responses. In that CLI context, --background is an optional boolean that determines whether the model response runs in the background. The page also displays --context-management and --conversation, but it does not state that they are interchangeable, mutually exclusive, or limited to one per request. Apply each control only for its documented purpose.

Keep CLI spelling separate from HTTP or SDK syntax. In particular, --context-management is the CLI option shown in the excerpt. The excerpt does not identify the corresponding raw JSON property name, so do not assume that the hyphenated option is a valid HTTP request key. Obtain the exact property name and value encoding from the complete HTTP or SDK schema used by the application.

Supported facts and evidence limits

Client execution and recovery guidance

1. Choose background execution only when the application can continue independently of the create call. Treat this as an application design decision; the excerpt does not describe how long the service retains work or results.
2. Use --conversation when its documented prepend-and-append behavior matches the required continuity. Configure --context-management only after verifying its accepted values and exact syntax in the complete contract. Do not assume that either control replaces the other.
3. Select custom code, web search, or file search according to task needs, data boundaries, and permissions. Verify the actual tools schema before implementing selection logic because the excerpt provides examples of tools, not a tool-choice protocol.
4. The presence of Retrieve a response makes retrieval a reasonable candidate for polling, but that is an architectural inference rather than a documented polling procedure. Check the full Retrieve contract for its lookup inputs, returned status information, terminal outcomes, and error cases before designing a loop.
5. Set polling cadence, backoff, timeout, and retry limits as explicit client policies. Avoid claiming a recommended interval or a safe retry rule from this excerpt, because neither is provided.
6. For restart recovery, keep an application job record in storage that survives the client process. If the full Retrieve contract supplies the necessary lookup mechanism, use it before creating replacement work. Add application-level duplicate protection where duplicate creation would be harmful; the excerpt promises neither automatic resumption nor deduplication.
7. Use Cancel or Compact only after reviewing each operation’s full contract. Their names in navigation do not prove when they are permitted or what state transition they cause.

Publication boundary

The official Create a response reference supports only the documented facts identified above. Client polling and recovery recommendations are clearly labeled as design guidance. The supplied excerpt does not show selectable model IDs, so this draft makes no model-availability claim.

Model availability note: The official source does not specify a selectable model ID.