> ## Documentation Index > Fetch the complete documentation index at: https://docs.mka1.com/llms.txt > Use this file to discover all available pages before exploring further. # Background responses > Run long-running responses in the background and retrieve results by polling or streaming. Use `background` mode when a response may take a long time to complete, such as multi-step tool use or large generation tasks. The API returns immediately with a queued response, and you retrieve the result later by polling or streaming. ## Create a background response Set `background` to `true` and `stream` to `false`. The API creates the response, starts processing it asynchronously, and returns immediately with `status: "queued"`. ```ts TypeScript SDK theme={null} import { SDK } from '@meetkai/mka1'; import type { ResponseObject } from '@meetkai/mka1/models/components'; const sdk = new SDK({ bearerAuth: 'Bearer ' }); const response = await sdk.llm.responses.create({ xOnBehalfOf: '', // optional — attribute the request to one of your end users responsesCreateRequest: { model: 'auto', input: 'Write a 500-word essay about the history of the internet.', background: true, stream: false, }, }) as ResponseObject; console.log(response.id, response.status); // resp_abc123 queued ``` ```ts OpenAI SDK theme={null} import OpenAI from 'openai'; const openai = new OpenAI({ apiKey: '', baseURL: 'https://apigw.mka1.com/api/v1/llm/', defaultHeaders: { 'X-On-Behalf-Of': '' }, }); const response = await openai.responses.create({ model: 'auto', input: 'Write a 500-word essay about the history of the internet.', background: true, stream: false, }); console.log(response.id, response.status); // resp_abc123 queued ``` ```python Python SDK theme={null} from meetkai_mka1 import SDK import time from meetkai_mka1.responses import GetAcceptEnum sdk = SDK(bearer_auth="Bearer ") res = sdk.llm.responses.create( model="auto", input="Write a 500-word essay about the history of the internet.", background=True, stream=False, x_on_behalf_of="", # optional — attribute the request to one of your end users ) print(res.id, res.status) # resp_abc123 queued ``` ```csharp C# SDK theme={null} using MeetKai.MKA1; using MeetKai.MKA1.Types.Components; using MeetKai.MKA1.Types.Requests; var sdk = new SDK(bearerAuth: "Bearer "); var res = await sdk.Llm.Responses.CreateAsync( body: new ResponsesCreateRequest() { Model = "auto", Input = ResponsesCreateRequestInput.CreateStr( "Write a 500-word essay about the history of the internet."), Background = true, Stream = false, }, xOnBehalfOf: "" // optional — attribute the request to one of your end users ); Console.WriteLine($"{res.ResponseObject!.Id} {res.ResponseObject!.Status}"); // resp_abc123 queued ``` ```bash CLI theme={null} mka1 llm responses create \ --background \ --model auto \ --input '"Write a 500-word essay about the history of the internet."' \ -H 'X-On-Behalf-Of: ' ``` ```bash Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/responses \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'X-On-Behalf-Of: ' \ --data '{ "model": "auto", "input": "Write a 500-word essay about the history of the internet.", "background": true, "stream": false }' ``` Save the `id` to retrieve the result later. ## Poll for the result Call `GET /responses/{response_id}` until the status reaches a terminal state. ```ts TypeScript SDK theme={null} let polled = await sdk.llm.responses.get({ responseId: response.id, xOnBehalfOf: '', }) as ResponseObject; while (polled.status === 'queued' || polled.status === 'in_progress') { await new Promise(r => setTimeout(r, 2000)); polled = await sdk.llm.responses.get({ responseId: response.id, xOnBehalfOf: '', }) as ResponseObject; } console.log(polled.status); // completed console.log(polled.output); ``` ```ts OpenAI SDK theme={null} let polled = await openai.responses.retrieve(response.id); while (polled.status === 'queued' || polled.status === 'in_progress') { await new Promise(r => setTimeout(r, 2000)); polled = await openai.responses.retrieve(response.id); } console.log(polled.status); // completed console.log(polled.output); ``` ```python Python SDK theme={null} polled = sdk.llm.responses.get( response_id=res.id, x_on_behalf_of="", ) while polled.status in ("queued", "in_progress"): time.sleep(2) polled = sdk.llm.responses.get( response_id=res.id, x_on_behalf_of="", ) print(polled.status) # completed print(polled.output) ``` ```csharp C# SDK theme={null} var polled = await sdk.Llm.Responses.GetAsync(new GetResponseRequest() { ResponseId = res.ResponseObject!.Id, XOnBehalfOf = "", }); while (polled.ResponseObject!.Status == "queued" || polled.ResponseObject!.Status == "in_progress") { await Task.Delay(2000); polled = await sdk.Llm.Responses.GetAsync(new GetResponseRequest() { ResponseId = res.ResponseObject!.Id, XOnBehalfOf = "", }); } Console.WriteLine(polled.ResponseObject!.Status); // completed ``` ```bash CLI theme={null} mka1 llm responses get --response-id resp_abc123 ``` ```bash Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123 \ --header 'Authorization: Bearer ' \ --header 'X-On-Behalf-Of: ' ``` A response moves through these statuses as it is processed: | Status | Meaning | | - | - | | `queued` | The request is waiting to be picked up | | `in_progress` | The model is generating output | | `completed` | Generation finished successfully | | `failed` | An error occurred during processing | | `incomplete` | The response was cut short (e.g. token limit) | | `cancelled` | The response was cancelled before completing | Poll at a reasonable interval (for example, every two seconds) until the status is no longer `queued` or `in_progress`. ## Stream events from a background response If you want real-time updates instead of polling, retrieve the response with `stream` set to `true`. The API returns server-sent events as the response is processed. ```ts TypeScript SDK theme={null} const streamed = await sdk.llm.responses.get({ responseId: response.id, stream: true, xOnBehalfOf: '', }); ``` ```ts OpenAI SDK theme={null} const stream = await openai.responses.retrieve(response.id, { stream: true, }); for await (const event of stream) { console.log(event.type); } ``` ```python Python SDK theme={null} streamed = sdk.llm.responses.get( response_id=res.id, stream=True, accept_header_override=GetAcceptEnum.TEXT_EVENT_STREAM, x_on_behalf_of="", ) for event in streamed: print(event.data.type) ``` ```csharp C# SDK theme={null} var streamed = await sdk.Llm.Responses.GetAsync(new GetResponseRequest() { ResponseId = res.ResponseObject!.Id, Stream = true, XOnBehalfOf = "", }); ``` ```bash CLI theme={null} mka1 llm responses get --response-id resp_abc123 --stream ``` ```bash Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123?stream=true \ --header 'Authorization: Bearer ' \ --header 'X-On-Behalf-Of: ' ``` Events arrive as they are produced. The stream closes after a terminal event such as `response.completed` or `response.failed`. If the response has already completed when you call this endpoint, you receive a single terminal event with the final response and the stream closes immediately. ## Stream events at creation time You can also stream events directly when creating a background response by setting both `background` and `stream` to `true`. ```ts TypeScript SDK theme={null} const result = await sdk.llm.responses.create({ xOnBehalfOf: '', responsesCreateRequest: { model: 'auto', input: 'Write a 500-word essay about the history of the internet.', background: true, stream: true, }, }); ``` ```ts OpenAI SDK theme={null} const stream = await openai.responses.create({ model: 'auto', input: 'Write a 500-word essay about the history of the internet.', background: true, stream: true, }); for await (const event of stream) { console.log(event.type); // response.queued → response.created → ... → response.completed } ``` ```python Python SDK theme={null} stream = sdk.llm.responses.create( model="auto", input="Write a 500-word essay about the history of the internet.", background=True, stream=True, x_on_behalf_of="", ) for event in stream: print(event.data.type) # response.queued → response.created → ... → response.completed ``` ```csharp C# SDK theme={null} var res = await sdk.Llm.Responses.CreateAsync( body: new ResponsesCreateRequest() { Model = "auto", Input = ResponsesCreateRequestInput.CreateStr( "Write a 500-word essay about the history of the internet."), Background = true, Stream = true, }, xOnBehalfOf: "" ); ``` ```bash CLI theme={null} mka1 llm responses create \ --background \ --stream \ --model auto \ --input '"Write a 500-word essay about the history of the internet."' ``` ```bash Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/responses \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'X-On-Behalf-Of: ' \ --data '{ "model": "auto", "input": "Write a 500-word essay about the history of the internet.", "background": true, "stream": true }' ``` The first event is `response.queued`, followed by `response.created`, intermediate events such as `response.output_text.delta`, and finally a terminal event like `response.completed`. This is useful when you want to show progress in a UI while the work runs in the background. If the client disconnects, the response continues processing and can be retrieved later. ## Cancel a background response If you no longer need the result, cancel a queued or in-progress response. ```ts TypeScript SDK theme={null} const cancelled = await sdk.llm.responses.cancel({ responseId: response.id, xOnBehalfOf: '', }); console.log(cancelled.status); // cancelled ``` ```ts OpenAI SDK theme={null} const cancelled = await openai.responses.cancel(response.id); console.log(cancelled.status); // cancelled ``` ```python Python SDK theme={null} cancelled = sdk.llm.responses.cancel( response_id=res.id, x_on_behalf_of="", ) print(cancelled.status) # cancelled ``` ```csharp C# SDK theme={null} var cancelled = await sdk.Llm.Responses.CancelAsync( responseId: res.ResponseObject!.Id, xOnBehalfOf: "" ); Console.WriteLine(cancelled.Status); // cancelled ``` ```bash CLI theme={null} mka1 llm responses cancel --response-id resp_abc123 ``` ```bash Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123/cancel \ --request POST \ --header 'Authorization: Bearer ' \ --header 'X-On-Behalf-Of: ' ``` The response status changes to `cancelled`. Responses that have already completed or failed cannot be cancelled. ## Pause and wake Add the `sleep` tool when a background response may need to wait, for example for a webhook it just triggered, or between checks on an outside job. The model calls `sleep` with either `duration_seconds` (1 to 1200) or `wake_at` (an ISO 8601 timestamp at most 20 minutes ahead), plus an optional `reason`. `sleep` only works with `background: true`. The gateway rejects a foreground request that lists it. To cut a sleep short, call the wake endpoint with follow-up input. The model receives that input as the tool's result and continues from it. The `sleep` tool type and the wake endpoint are gateway extensions the OpenAI SDK does not know, and the `mka1` CLI reference documents no `responses wake` command, so this section shows the MKA1 SDKs and curl. ```ts TypeScript SDK theme={null} const sleeping = await sdk.llm.responses.create({ xOnBehalfOf: '', responsesCreateRequest: { model: 'auto', input: 'Sleep for 120 seconds, then summarize any follow-up I send. If I send nothing, say so.', tools: [{ type: 'sleep' }], background: true, stream: false, }, }) as ResponseObject; // Later, once the response is sleeping const wake = await sdk.llm.responses.wake({ xOnBehalfOf: '', responseId: sleeping.id, requestBody: { input: 'Follow-up: the deploy finished. Summarize that.' }, }); console.log(wake.object, wake.response_id); // response.sleep_wake resp_abc123 ``` ```python Python SDK theme={null} sleeping = sdk.llm.responses.create( model="auto", input="Sleep for 120 seconds, then summarize any follow-up I send. If I send nothing, say so.", tools=[{"type": "sleep"}], background=True, stream=False, x_on_behalf_of="", ) # Later, once the response is sleeping wake = sdk.llm.responses.wake( response_id=sleeping.id, input="Follow-up: the deploy finished. Summarize that.", x_on_behalf_of="", ) print(wake.object, wake.response_id) # response.sleep_wake resp_abc123 ``` ```csharp C# SDK theme={null} var sleeping = await sdk.Llm.Responses.CreateAsync( body: new ResponsesCreateRequest() { Model = "auto", Input = ResponsesCreateRequestInput.CreateStr( "Sleep for 120 seconds, then summarize any follow-up I send. If I send nothing, say so."), Tools = new List { ResponsesCreateRequestTool.CreateSleepToolDefinition(new SleepToolDefinition()), }, Background = true, Stream = false, }, xOnBehalfOf: "" ); // Later, once the response is sleeping var wake = await sdk.Llm.Responses.WakeAsync( responseId: sleeping.ResponseObject!.Id, body: new WakeResponseRequestBody() { Input = "Follow-up: the deploy finished. Summarize that." }, xOnBehalfOf: "" ); ``` ```bash Bash theme={null} curl https://apigw.mka1.com/api/v1/llm/responses \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'X-On-Behalf-Of: ' \ --data '{ "model": "auto", "input": "Sleep for 120 seconds, then summarize any follow-up I send. If I send nothing, say so.", "tools": [{ "type": "sleep" }], "background": true, "stream": false }' # Later, once the response is sleeping curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123/wake \ --request POST \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \ --header 'X-On-Behalf-Of: ' \ --data '{ "input": "Follow-up: the deploy finished. Summarize that." }' ``` While it sleeps, the response keeps `status: "in_progress"`; there is no separate sleeping status, so polling cannot tell you it is asleep. Stream its events as shown above and wait for `response.sleep_call.sleeping`, or call wake and retry on `409`. A sleep appears in the stream as three events: `response.sleep_call.in_progress` with the model's `args`, `response.sleep_call.sleeping` with the resolved `wake_at`, and `response.sleep_call.completed` with a `status` of `woke`, `interrupted`, or `cancelled`. The `function_call_output` on that last event is the JSON the model received. When the timer runs out, the model receives `{"status": "woke", "slept_seconds": ..., "wake_at": ...}`, plus `reason` if it gave one. When you wake it, the model receives `{"status": "interrupted", "input": ..., "slept_seconds": ..., "wake_at": ..., "interrupted_at": ...}`, again with `reason` if given. If the input was cut, the payload also carries `input_truncated: true` and `original_input_length`. Cancelling the response ends the sleep with `status: "cancelled"`. The wake call returns one of two statuses: | Status | Meaning | | - | - | | `200` | `{"object": "response.sleep_wake", "response_id": ..., "created_at": ...}` as soon as the signal is stored. The sleeping response checks for it once a second, so allow up to a second of delay. | | `409` | The response is not sleeping right now, is not a background response, has already finished, or already has a wake waiting. If you race the model, wait a moment and retry. | `input` is trimmed and must then be 1 to 20,000 characters, so whitespace-only input is rejected; the model sees the first 8,000. Wake calls are limited to 30 per minute for each API key and end user, and further calls are blocked for 10 seconds once you exceed that. ## Next steps * See [generate a response](/docs/generate-a-response) for the basics of creating responses * See [manage agents](/docs/managing-agents) when you want reusable agent definitions and persisted runs * Review the [Responses API reference](/api-reference/introduction) for the full list of parameters and response fields This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.