Repository Public
1# Background mode23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Agents like [Codex](https://openai.com/index/introducing-codex/) and [Deep Research](https://openai.com/index/introducing-deep-research/) show that reasoning models can take several minutes to solve complex problems. Background mode enables you to execute long-running tasks on models like GPT-5.2 and GPT-5.2 Pro reliably, without having to worry about timeouts or other connectivity issues.67Background mode kicks off these tasks asynchronously, and developers can poll response objects to check status over time. To start response generation in the background, make an API request with `background` set to `true`:89Background requests from Zero Data Retention (ZDR) projects run with10 `store=false`. Response data is temporarily stored to disk for roughly 1011 minutes to enable asynchronous execution and polling.1213For projects using [Modified Abuse14Monitoring](https://developers.openai.com/api/docs/guides/your-data#modified-abuse-monitoring), including15enhanced Modified Abuse Monitoring, foreground requests follow standard16retention when `store` is omitted or set to `true`. Background responses are17retained after the polling period only when `store=true` is explicitly provided.18If `store` is omitted or set to `false` for a background request, the response19is deleted after roughly 10 minutes.2021Generate a response in the background2223```bash24curl https://api.openai.com/v1/responses \25-H "Content-Type: application/json" \26-H "Authorization: Bearer $OPENAI_API_KEY" \27-d '{28 "model": "gpt-6-astra",29 "input": "Write a very long novel about otters in space.",30 "background": true31}'32```3334```javascript35import OpenAI from "openai";36const client = new OpenAI();3738const resp = await client.responses.create({39 model: "gpt-6-astra",40 input: "Write a very long novel about otters in space.",41 background: true,42});4344console.log(resp.status);45```4647```python48from openai import OpenAI4950client = OpenAI()5152resp = client.responses.create(53 model="gpt-6-astra",54 input="Write a very long novel about otters in space.",55 background=True,56)5758print(resp.status)59```6061```go62package main6364import (65 "context"66 "fmt"6768 "github.com/openai/openai-go/v3"69 "github.com/openai/openai-go/v3/responses"70)7172func main() {73 client := openai.NewClient()7475 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{76 Model: "gpt-6-astra",77 Background: openai.Bool(true),78 Input: responses.ResponseNewParamsInputUnion{79 OfString: openai.String("Write a very long novel about otters in space."),80 },81 })82 if err != nil {83 panic(err)84 }8586 fmt.Println(response.Status)87}88```8990```java91import com.openai.client.OpenAIClient;92import com.openai.client.okhttp.OpenAIOkHttpClient;93import com.openai.models.responses.ResponseCreateParams;9495ResponseCreateParams params =96 ResponseCreateParams.builder()97 .model("gpt-6-astra")98 .input("Write a detailed market analysis.")99 .background(true)100 .build();101102var response = client.responses().create(params);103System.out.println(response.status().orElseThrow());104```105106```csharp107using OpenAI.Responses;108#pragma warning disable OPENAI001109110string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;111ResponsesClient client = new(key);112113CreateResponseOptions options = new()114{115 Model = "gpt-6-astra",116 BackgroundModeEnabled = true,117};118options.InputItems.Add(119 ResponseItem.CreateUserMessageItem("Write a very long novel about otters in space.")120);121122ResponseResult response = await client.CreateResponseAsync(options);123Console.WriteLine(response.Status);124```125126```ruby127require "openai"128129client = OpenAI::Client.new130response = client.responses.create(131 model: "gpt-6-astra",132 input: "Write a detailed market analysis.",133 background: true134)135136puts(response.status)137```138139140## Polling background responses141142To check the status of background requests, use the GET endpoint for Responses. Keep polling while the request is in the queued or in_progress state. When it leaves these states, it has reached a final (terminal) state.143144Retrieve a response executing in the background145146```bash147curl https://api.openai.com/v1/responses/resp_123 \148 -H "Content-Type: application/json" \149 -H "Authorization: Bearer $OPENAI_API_KEY"150```151152```javascript153import OpenAI from "openai";154const client = new OpenAI();155156let resp = await client.responses.create({157 model: "gpt-6-astra",158 input: "Write a very long novel about otters in space.",159 background: true,160});161162while (resp.status === "queued" || resp.status === "in_progress") {163 console.log("Current status: " + resp.status);164 await new Promise((resolve) => setTimeout(resolve, 2000)); // wait 2 seconds165 resp = await client.responses.retrieve(resp.id);166}167168console.log("Final status: " + resp.status + "\nOutput:\n" + resp.output_text);169```170171```python172from openai import OpenAI173from time import sleep174175client = OpenAI()176177resp = client.responses.create(178 model="gpt-6-astra",179 input="Write a very long novel about otters in space.",180 background=True,181)182183while resp.status in {"queued", "in_progress"}:184 print(f"Current status: {resp.status}")185 sleep(2)186 resp = client.responses.retrieve(resp.id)187188print(f"Final status: {resp.status}\nOutput:\n{resp.output_text}")189```190191```go192package main193194import (195 "context"196 "fmt"197 "time"198199 "github.com/openai/openai-go/v3"200 "github.com/openai/openai-go/v3/responses"201)202203func main() {204 client := openai.NewClient()205206 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{207 Model: "gpt-6-astra",208 Background: openai.Bool(true),209 Input: responses.ResponseNewParamsInputUnion{210 OfString: openai.String("Write a very long novel about otters in space."),211 },212 })213 if err != nil {214 panic(err)215 }216217 for response.Status == "queued" || response.Status == "in_progress" {218 fmt.Println("Current status:", response.Status)219 time.Sleep(2 * time.Second)220 response, err = client.Responses.Get(context.Background(), response.ID, responses.ResponseGetParams{})221 if err != nil {222 panic(err)223 }224 }225226 fmt.Printf("Final status: %s\nOutput:\n%s\n", response.Status, response.OutputText())227}228```229230```java231import com.openai.client.OpenAIClient;232import com.openai.client.okhttp.OpenAIOkHttpClient;233import com.openai.models.responses.ResponseCreateParams;234import com.openai.models.responses.ResponseStatus;235236ResponseCreateParams params =237 ResponseCreateParams.builder()238 .model("gpt-6-astra")239 .input("Write a very long novel about otters in space.")240 .background(true)241 .build();242243var response = client.responses().create(params);244while (response.status().filter(ResponseStatus.QUEUED::equals).isPresent()245 || response.status().filter(ResponseStatus.IN_PROGRESS::equals).isPresent()) {246 System.out.println("Current status: " + response.status().orElseThrow());247 Thread.sleep(1000);248 response = client.responses().retrieve(response.id());249}250System.out.println("Final status: " + response.status().orElseThrow());251response.output().stream()252 .flatMap(item -> item.message().stream())253 .flatMap(message -> message.content().stream())254 .flatMap(content -> content.outputText().stream())255 .forEach(text -> System.out.println(text.text()));256```257258```csharp259using OpenAI.Responses;260#pragma warning disable OPENAI001261262string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;263ResponsesClient client = new(key);264265CreateResponseOptions options = new()266{267 Model = "gpt-6-astra",268 BackgroundModeEnabled = true,269};270options.InputItems.Add(271 ResponseItem.CreateUserMessageItem("Write a very long novel about otters in space.")272);273274ResponseResult created = await client.CreateResponseAsync(options);275ResponseResult response = await client.GetResponseAsync(created.Id);276while (response.Status is ResponseStatus.Queued or ResponseStatus.InProgress)277{278 await Task.Delay(TimeSpan.FromSeconds(1));279 response = await client.GetResponseAsync(response.Id);280}281if (response.Status != ResponseStatus.Completed)282{283 throw new InvalidOperationException($"Background response ended with status: {response.Status}");284}285Console.WriteLine($"Status: {response.Status}");286Console.WriteLine(response.GetOutputText());287```288289```ruby290require "openai"291292client = OpenAI::Client.new293response = client.responses.create(294 model: "gpt-6-astra",295 input: "Write a very long novel about otters in space.",296 background: true297)298299while [:queued, :in_progress].include?(response.status)300 puts("Current status: #{response.status}")301 sleep(2)302 response = client.responses.retrieve(response.id)303end304305puts("Final status: #{response.status}")306puts(response.output_text)307```308309310## Cancelling a background response311312You can also cancel an in-flight response like this:313314Cancel an ongoing response315316```bash317curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \318 -H "Content-Type: application/json" \319 -H "Authorization: Bearer $OPENAI_API_KEY"320```321322```javascript323import OpenAI from "openai";324const client = new OpenAI();325326const resp = await client.responses.cancel("resp_123");327328console.log(resp.status);329```330331```python332import os333334from openai import OpenAI335336response_id = os.environ["OPENAI_RESPONSE_ID"]337client = OpenAI()338339resp = client.responses.cancel(response_id)340341print(resp.status)342```343344```go345package main346347import (348 "context"349 "fmt"350351 "github.com/openai/openai-go/v3"352)353354func main() {355 client := openai.NewClient()356357 canceled, err := client.Responses.Cancel(context.Background(), "resp_123")358 if err != nil {359 panic(err)360 }361362 fmt.Println(canceled.Status)363}364```365366```java367import com.openai.client.OpenAIClient;368import com.openai.client.okhttp.OpenAIOkHttpClient;369370String responseId = "resp_123";371372var response = client.responses().cancel(responseId);373374System.out.println(response.status());375```376377```csharp378using OpenAI.Responses;379#pragma warning disable OPENAI001380381string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;382ResponsesClient client = new(key);383384// Replace this illustrative ID with the background response to cancel.385string responseId = "resp_123";386387ResponseResult response = await client.CancelResponseAsync(responseId);388Console.WriteLine(response.Status);389```390391```ruby392require "openai"393394client = OpenAI::Client.new395response = client.responses.cancel("resp_123")396puts(response.status)397```398399400Cancelling twice is idempotent - subsequent calls simply return the final `Response` object.401402## Streaming a background response403404You can create a background Response and start streaming events from it right away. This may be helpful if you expect the client to drop the stream and want the option of picking it back up later. To do this, create a Response with both `background` and `stream` set to `true`. You will want to keep track of a "cursor" corresponding to the `sequence_number` you receive in each streaming event.405406Currently, the time to first token you receive from a background response is407 higher than what you receive from a synchronous one. We are working to reduce408 this latency gap in the coming weeks.409410Generate and stream a background response411412```bash413curl https://api.openai.com/v1/responses \414-H "Content-Type: application/json" \415-H "Authorization: Bearer $OPENAI_API_KEY" \416-d '{417 "model": "gpt-6-astra",418 "input": "Write a very long novel about otters in space.",419 "background": true,420 "stream": true421}'422423// To resume:424curl "https://api.openai.com/v1/responses/resp_123?stream=true&starting_after=42" \425-H "Content-Type: application/json" \426-H "Authorization: Bearer $OPENAI_API_KEY"427```428429```javascript430import OpenAI from "openai";431const client = new OpenAI();432433const stream = await client.responses.create({434 model: "gpt-6-astra",435 input: "Write a very long novel about otters in space.",436 background: true,437 stream: true,438});439440let cursor = null;441for await (const event of stream) {442 console.log(event);443 cursor = event.sequence_number;444}445446// If the connection drops, you can resume streaming from the last cursor (SDK support coming soon):447// const resumedStream = await client.responses.stream(resp.id, { starting_after: cursor });448// for await (const event of resumedStream) { ... }449```450451```python452from openai import OpenAI453454client = OpenAI()455456# Fire off an async response but also start streaming immediately457stream = client.responses.create(458 model="gpt-6-astra",459 input="Write a very long novel about otters in space.",460 background=True,461 stream=True,462)463464cursor = None465for event in stream:466 print(event)467 cursor = event.sequence_number468469# If your connection drops, the response continues running and you can reconnect:470# SDK support for resuming the stream is coming soon.471# for event in client.responses.stream(resp.id, starting_after=cursor):472# print(event)473```474475```go476package main477478import (479 "context"480 "fmt"481482 "github.com/openai/openai-go/v3"483 "github.com/openai/openai-go/v3/responses"484)485486func main() {487 client := openai.NewClient()488489 stream := client.Responses.NewStreaming(context.Background(), responses.ResponseNewParams{490 Model: "gpt-6-astra",491 Background: openai.Bool(true),492 Input: responses.ResponseNewParamsInputUnion{493 OfString: openai.String("Write a very long novel about otters in space."),494 },495 })496 var cursor int64497 var responseID string498 for stream.Next() {499 event := stream.Current()500 fmt.Println(event.Type)501 cursor = event.SequenceNumber502 if event.Response.ID != "" {503 responseID = event.Response.ID504 }505 }506 if err := stream.Err(); err != nil {507 panic(err)508 }509 fmt.Printf("response %s last cursor %d\n", responseID, cursor)510511 // If the connection drops, resume streaming from the last cursor:512 // resumed := client.Responses.GetStreaming(513 // context.Background(),514 // responseID,515 // responses.ResponseGetParams{StartingAfter: openai.Int(cursor)},516 // )517 // for resumed.Next() {518 // fmt.Println(resumed.Current().Type)519 // }520}521```522523```java524import com.fasterxml.jackson.databind.json.JsonMapper;525import com.openai.client.OpenAIClient;526import com.openai.client.okhttp.OpenAIOkHttpClient;527import com.openai.core.http.StreamResponse;528import com.openai.models.responses.ResponseCreateParams;529import com.openai.models.responses.ResponseRetrieveParams;530import com.openai.models.responses.ResponseStreamEvent;531import java.util.concurrent.atomic.AtomicBoolean;532import java.util.concurrent.atomic.AtomicLong;533import java.util.concurrent.atomic.AtomicReference;534535ResponseCreateParams params =536 ResponseCreateParams.builder()537 .model("gpt-6-astra")538 .input("Write a very long novel about otters in space.")539 .background(true)540 .build();541542AtomicLong lastSequenceNumber = new AtomicLong(-1);543AtomicReference<String> responseId = new AtomicReference<>("");544AtomicBoolean streamCompleted = new AtomicBoolean(false);545JsonMapper json = new JsonMapper();546try (StreamResponse<ResponseStreamEvent> stream = client.responses().createStreaming(params)) {547 stream.stream()548 .forEach(549 event -> {550 lastSequenceNumber.set(json.valueToTree(event).path("sequence_number").asLong());551 event552 .created()553 .ifPresent(554 created -> {555 responseId.set(created.response().id());556 System.out.println("response.created");557 });558 event559 .outputTextDelta()560 .ifPresent(561 delta -> {562 System.out.println("response.output_text.delta");563 });564 event565 .completed()566 .ifPresent(567 completed -> {568 streamCompleted.set(true);569 System.out.println("response.completed");570 });571 });572}573System.out.println(574 "Response " + responseId.get() + "; last sequence number " + lastSequenceNumber.get());575if (!streamCompleted.get()) {576 try (StreamResponse<ResponseStreamEvent> resumed =577 client578 .responses()579 .retrieveStreaming(580 ResponseRetrieveParams.builder()581 .responseId(responseId.get())582 .startingAfter(lastSequenceNumber.get())583 .build())) {584 resumed.stream()585 .forEach(586 event ->587 event.outputTextDelta().ifPresent(delta -> System.out.println(delta.delta())));588 }589}590```591592```csharp593using OpenAI.Responses;594#pragma warning disable OPENAI001595596string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;597ResponsesClient client = new(key);598599CreateResponseOptions options = new()600{601 Model = "gpt-6-astra",602 BackgroundModeEnabled = true,603 StreamingEnabled = true,604};605options.InputItems.Add(606 ResponseItem.CreateUserMessageItem("Write a very long novel about otters in space.")607);608609string? responseId = null;610int lastSequenceNumber = -1;611bool completed = false;612613void HandleUpdate(StreamingResponseUpdate update)614{615 lastSequenceNumber = update.SequenceNumber;616 switch (update)617 {618 case StreamingResponseCreatedUpdate created:619 responseId = created.Response.Id;620 break;621 case StreamingResponseOutputTextDeltaUpdate text:622 Console.Write(text.Delta);623 break;624 case StreamingResponseCompletedUpdate:625 completed = true;626 break;627 case StreamingResponseFailedUpdate:628 throw new InvalidOperationException("The background response failed.");629 case StreamingResponseIncompleteUpdate:630 throw new InvalidOperationException("The background response was incomplete.");631 case StreamingResponseErrorUpdate error:632 throw new InvalidOperationException($"The response stream failed: {error.Message}");633 }634}635636try637{638 await foreach (639 StreamingResponseUpdate update in client.CreateResponseStreamingAsync(options)640 )641 {642 HandleUpdate(update);643 }644}645catch (Exception error)646 when (error is HttpRequestException or IOException && responseId is not null)647{648 // The background response continues after its streaming connection is interrupted.649}650651if (!completed)652{653 if (responseId is null)654 {655 throw new InvalidOperationException("The response stream ended before providing its ID.");656 }657658 GetResponseOptions resumeOptions = new(responseId)659 {660 StartingAfter = lastSequenceNumber,661 StreamingEnabled = true,662 };663 await foreach (StreamingResponseUpdate update in client.GetResponseStreamingAsync(resumeOptions))664 {665 HandleUpdate(update);666 }667668 if (!completed)669 {670 throw new InvalidOperationException(671 "The resumed response stream ended before the background response completed."672 );673 }674}675```676677```ruby678require "openai"679680client = OpenAI::Client.new681stream = client.responses.stream(682 model: "gpt-6-astra",683 input: "Write a very long novel about otters in space.",684 background: true685)686687last_sequence_number = -1688response_id = ""689stream.each do |event|690 puts(event.type)691 last_sequence_number = event.sequence_number || last_sequence_number692 if event.is_a?(OpenAI::Models::Responses::ResponseCreatedEvent)693 response_id = event.response.id694 end695end696697puts("Response #{response_id}; last sequence number #{last_sequence_number}")698699# If the connection drops, resume from the last sequence number:700# client.responses.stream(response_id: response_id, starting_after: last_sequence_number).each do |event|701# puts(event.type)702# end703```704705706## Limits7077081. Background requests can use `store=false`, but response data is temporarily709 stored to support asynchronous execution and polling.7102. To cancel a synchronous response, terminate the connection7113. You can only start a new stream from a background response if you created it with `stream=true`.