> ## 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"`.
```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: '
```
```ts MKA1 SDK theme={null}
import { SDK } from '@meetkai/mka1';
import type { ResponseObject } from '@meetkai/mka1/models/components';
const mka1 = new SDK({
bearerAuth: `Bearer ${YOUR_API_KEY}`,
});
const response = await mka1.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
```
```csharp C# SDK theme={null}
using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");
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
```
```python Python SDK theme={null}
from meetkai_mka1 import SDK
sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")
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
```
```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.
```bash CLI theme={null}
mka1 llm responses get --response-id resp_abc123
```
```ts MKA1 SDK theme={null}
let polled = await mka1.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 mka1.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);
```
```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
```
```python Python SDK theme={null}
import time
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)
```
```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.
```bash CLI theme={null}
mka1 llm responses get --response-id resp_abc123 --stream
```
```ts MKA1 SDK theme={null}
const streamed = await mka1.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);
}
```
```csharp C# SDK theme={null}
var streamed = await sdk.Llm.Responses.GetAsync(new GetResponseRequest()
{
ResponseId = res.ResponseObject!.Id,
Stream = true,
XOnBehalfOf = "",
});
```
```python Python SDK theme={null}
from meetkai_mka1.responses import GetAcceptEnum
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)
```
```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`.
```bash CLI theme={null}
mka1 llm responses create \
--background \
--stream \
--model auto \
--input '"Write a 500-word essay about the history of the internet."'
```
```ts MKA1 SDK theme={null}
const result = await mka1.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
}
```
```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: ""
);
```
```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
```
```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.
```bash CLI theme={null}
mka1 llm responses cancel --response-id resp_abc123
```
```ts MKA1 SDK theme={null}
const cancelled = await mka1.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
```
```csharp C# SDK theme={null}
var cancelled = await sdk.Llm.Responses.CancelAsync(
responseId: res.ResponseObject!.Id,
xOnBehalfOf: ""
);
Console.WriteLine(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
```
```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.
## 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