Background Agent Runs — Async Execution API

Submit agent runs that execute asynchronously and poll for completion — ideal for long-running tasks and batch processing pipelines.

Background runs let you submit an agent task and receive an immediate acknowledgement, then poll for the result at your own pace. This is the right choice for long-running analyses, batch processing, and workflow steps where you cannot hold an HTTP connection open for the full duration of execution.

All requests require a valid bearer token in the Authorization header.

---

Submit a background run

POST /api/agents/{agentId}/runs/background

Queues the agent run for asynchronous execution and returns immediately with a runId and status: "QUEUED". The request accepts the same body as the synchronous run endpoint.

Path parameters

agentId · string · required

The unique identifier of the agent to run.

Request body

message · string · required

The user’s input or query for the agent.

sessionId · string

UUID of an existing session to continue. Omit to start a new session — the server generates one automatically.

userId · string

Associates the run with a specific user for memory scoping and audit trails.

orgId · string

Tenant identifier for multi-tenant deployments.

generateFollowups · boolean · default: "false"

When true, the agent generates suggested follow-up questions appended to the output.

media · object[]

Array of multimodal inputs. Each entry contains type (MIME type) and data (base64 or URL).

options · object

Optional model overrides (model, temperature, maxTokens).

Response

runId · string · required

Unique identifier for the queued run. Use this to poll for status.

status · string · required

Always "QUEUED" on successful submission.

cURL

curl --request POST \
  --url "http://localhost:8080/api/agents/finance_agent/runs/background" \
  --header "Authorization: Bearer {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "message": "Analyze Q3 2025 earnings for the top 10 S&P 500 constituents.",
    "userId": "user_abc123",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Example response

{
  "runId": "run_7f3a9c12-4e2b-4d1a-8c5f-abc123def456",
  "status": "QUEUED"
}

---

Poll for run status

GET /api/agents/{agentId}/runs/{runId}/status

Returns the current state of a background run as an AgentRun entity. Poll this endpoint until status reaches a terminal state (COMPLETED, FAILED, or CANCELLED).

agentId · string · required

The agent that owns the run.

runId · string · required

The run identifier returned when the background run was submitted.

Run status values

Status	Description
QUEUED	The run has been accepted and is waiting in the job queue.
RUNNING	The agent is actively processing the request.
COMPLETED	Execution finished successfully. Check output for the response.
FAILED	An unrecoverable error occurred.
PAUSED	The agent triggered a Human-in-the-Loop gate. Call /runs/{runId}/continue to approve or reject.
CANCELLED	The run was cancelled via DELETE /api/agents/{agentId}/runs/{runId}.

id · string

The run ID.

agentId · string

The agent that executed this run.

sessionId · string

The session this run belongs to.

status · string

Current execution status.

createdAt · string

ISO-8601 timestamp when the run was queued.

completedAt · string

ISO-8601 timestamp when the run reached a terminal status. null while still running.

output · string

The agent’s response content, available when status is "COMPLETED".

cURL

curl --request GET \
  --url "http://localhost:8080/api/agents/finance_agent/runs/run_7f3a9c12/status" \
  --header "Authorization: Bearer {token}"

Example response (completed)

{
  "id": "run_7f3a9c12-4e2b-4d1a-8c5f-abc123def456",
  "agentId": "finance_agent",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED",
  "createdAt": "2026-05-06T10:00:00Z",
  "completedAt": "2026-05-06T10:00:47Z",
  "output": "## Q3 2025 Earnings Summary\n\nApple (AAPL): Revenue $94.9B, EPS $1.64..."
}

---

Batch status polling

GET /api/agents/{agentId}/runs/status?runIds=id1,id2,id3

Check the status of up to 100 background runs in a single HTTP request. Run IDs that have no corresponding record are silently omitted from the response.

agentId · string · required

The agent that owns the runs.

runIds · string · required

Comma-separated list of run IDs to check. Maximum 100 IDs per request.

cURL

curl --request GET \
  --url "http://localhost:8080/api/agents/finance_agent/runs/status?runIds=run_7f3a9c12,run_8a4b2d34,run_9c5e3f56" \
  --header "Authorization: Bearer {token}"

Example response

[
  {
    "id": "run_7f3a9c12-4e2b-4d1a-8c5f-abc123def456",
    "status": "COMPLETED",
    "createdAt": "2026-05-06T10:00:00Z",
    "completedAt": "2026-05-06T10:00:47Z"
  },
  {
    "id": "run_8a4b2d34-1c3e-4f2a-9d6b-bcd234ef5678",
    "status": "RUNNING",
    "createdAt": "2026-05-06T10:01:00Z",
    "completedAt": null
  }
]

---

Polling loop example

The following TypeScript example submits a background run and polls for completion with exponential backoff:

TypeScript

interface AgentRun {
  id: string;
  status: string;
  output?: string;
  completedAt?: string;
}

async function runInBackground(
  agentId: string,
  message: string,
  token: string
): Promise<AgentRun> {
  const baseUrl = "http://localhost:8080";

  // Submit the background run
  const submitRes = await fetch(
    `${baseUrl}/api/agents/${agentId}/runs/background`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ message }),
    }
  );

  const { runId } = await submitRes.json();
  console.log(`Run queued: ${runId}`);

  // Poll until terminal state
  const TERMINAL = new Set(["COMPLETED", "FAILED", "CANCELLED"]);
  let delayMs = 1000;

  while (true) {
    await new Promise((r) => setTimeout(r, delayMs));

    const statusRes = await fetch(
      `${baseUrl}/api/agents/${agentId}/runs/${runId}/status`,
      { headers: { Authorization: `Bearer ${token}` } }
    );

    const run: AgentRun = await statusRes.json();
    console.log(`Status: ${run.status}`);

    if (TERMINAL.has(run.status)) {
      if (run.status === "COMPLETED") {
        console.log("Output:", run.output);
      } else {
        console.error("Run did not complete:", run.status);
      }
      return run;
    }

    // Exponential backoff, capped at 10 seconds
    delayMs = Math.min(delayMs * 1.5, 10_000);
  }
}

runInBackground(
  "finance_agent",
  "Analyze Q3 2025 earnings for the top 10 S&P 500 constituents.",
  "your-token-here"
);

For batch workloads, use the batch status endpoint (?runIds=...) instead of individual polling calls. Checking 10 runs at once with one request every 3 seconds uses ~20 requests/minute compared to ~200 for individual polls.