Background responses

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".

mka1 llm responses create \
  --background \
  --model auto \
  --input '"Write a 500-word essay about the history of the internet."' \
  -H 'X-On-Behalf-Of: <end-user-id>'

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: '<end-user-id>', // 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

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: '<mka1-api-key>',
  baseURL: 'https://apigw.mka1.com/api/v1/llm/',
  defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
});

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

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: "<end-user-id>" // optional — attribute the request to one of your end users
);

Console.WriteLine($"{res.ResponseObject!.Id} {res.ResponseObject!.Status}"); // resp_abc123 queued

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="<end-user-id>",  # optional — attribute the request to one of your end users
)

print(res.id, res.status)  # resp_abc123 queued

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --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.

mka1 llm responses get --response-id resp_abc123

let polled = await mka1.llm.responses.get({
  responseId: response.id,
  xOnBehalfOf: '<end-user-id>',
}) 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: '<end-user-id>',
  }) as ResponseObject;
}

console.log(polled.status); // completed
console.log(polled.output);

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);

var polled = await sdk.Llm.Responses.GetAsync(new GetResponseRequest()
{
    ResponseId = res.ResponseObject!.Id,
    XOnBehalfOf = "<end-user-id>",
});

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 = "<end-user-id>",
    });
}

Console.WriteLine(polled.ResponseObject!.Status); // completed

import time

polled = sdk.llm.responses.get(
    response_id=res.id,
    x_on_behalf_of="<end-user-id>",
)

while polled.status in ("queued", "in_progress"):
    time.sleep(2)
    polled = sdk.llm.responses.get(
        response_id=res.id,
        x_on_behalf_of="<end-user-id>",
    )

print(polled.status)  # completed
print(polled.output)

curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123 \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

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.

mka1 llm responses get --response-id resp_abc123 --stream

const streamed = await mka1.llm.responses.get({
  responseId: response.id,
  stream: true,
  xOnBehalfOf: '<end-user-id>',
});

const stream = await openai.responses.retrieve(response.id, {
  stream: true,
});

for await (const event of stream) {
  console.log(event.type);
}

var streamed = await sdk.Llm.Responses.GetAsync(new GetResponseRequest()
{
    ResponseId = res.ResponseObject!.Id,
    Stream = true,
    XOnBehalfOf = "<end-user-id>",
});

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="<end-user-id>",
)

for event in streamed:
    print(event.data.type)

curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123?stream=true \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

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.

mka1 llm responses create \
  --background \
  --stream \
  --model auto \
  --input '"Write a 500-word essay about the history of the internet."'

const result = await mka1.llm.responses.create({
  xOnBehalfOf: '<end-user-id>',
  responsesCreateRequest: {
    model: 'auto',
    input: 'Write a 500-word essay about the history of the internet.',
    background: true,
    stream: true,
  },
});

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
}

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: "<end-user-id>"
);

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="<end-user-id>",
)

for event in stream:
    print(event.data.type)
    # response.queued → response.created → ... → response.completed

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --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.

mka1 llm responses cancel --response-id resp_abc123

const cancelled = await mka1.llm.responses.cancel({
  responseId: response.id,
  xOnBehalfOf: '<end-user-id>',
});

console.log(cancelled.status); // cancelled

const cancelled = await openai.responses.cancel(response.id);

console.log(cancelled.status); // cancelled

var cancelled = await sdk.Llm.Responses.CancelAsync(
    responseId: res.ResponseObject!.Id,
    xOnBehalfOf: "<end-user-id>"
);

Console.WriteLine(cancelled.Status); // cancelled

cancelled = sdk.llm.responses.cancel(
    response_id=res.id,
    x_on_behalf_of="<end-user-id>",
)

print(cancelled.status)  # cancelled

curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123/cancel \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

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.

const sleeping = await mka1.llm.responses.create({
  xOnBehalfOf: '<end-user-id>',
  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 mka1.llm.responses.wake({
  xOnBehalfOf: '<end-user-id>',
  responseId: sleeping.id,
  requestBody: { input: 'Follow-up: the deploy finished. Summarize that.' },
});

console.log(wake.object, wake.responseId); // response.sleep_wake resp_abc123

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using MeetKai.MKA1.Types.Requests;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

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>
        {
            ResponsesCreateRequestTool.CreateSleepToolDefinition(new SleepToolDefinition()),
        },
        Background = true,
        Stream = false,
    },
    xOnBehalfOf: "<end-user-id>"
);

// 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: "<end-user-id>"
);

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="<end-user-id>",
)

# 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="<end-user-id>",
)

print(wake.object, wake.response_id)  # response.sleep_wake resp_abc123

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --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 <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --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 for the basics of creating responses
See manage agents when you want reusable agent definitions and persisted runs
Review the Responses API reference for the full list of parameters and response fields

Getting started

Responses

Features

Compute

CLI

Recipes

Benchmarks

Infrastructure

Background responses

Create a background response

Poll for the result

Stream events from a background response

Stream events at creation time

Cancel a background response

Pause and wake

Next steps

​Create a background response

​Poll for the result

​Stream events from a background response

​Stream events at creation time

​Cancel a background response

​Pause and wake

​Next steps

Create a background response

Poll for the result

Stream events from a background response

Stream events at creation time

Cancel a background response

Pause and wake

Next steps