Async & Background Runs

Base URL: https://agent-api.auteryn.ai

There are two ways to run an agent without holding an SSE connection open:

Approach	When to use
POST /api/run with stream: false	Interactive clients that will reconnect to the stream. Returns 202 and dispatches to a worker. See Run an Agent.
POST /api/run/async	Server-to-server / webhook-driven background work. Returns 202 immediately and delivers the result via an SQS callback. Documented below.

---

POST /api/run/async

Accepts a run, returns 202 Accepted immediately, then executes in the background. This is the endpoint the flow workers use for messaging channels (Telegram, WhatsApp, etc.) and that external systems use for async processing.

Not available to guests. Guests must use POST /api/run. Messaging trigger sources (telegram, whatsapp, twilio, sms) require a customer-facing agent.

Request

POST https://agent-api.auteryn.ai/api/run/async
Authorization: Bearer <jwt>
X-Agent-Id: your-agent-uuid
Content-Type: application/json

Body:

{
  "query": "Summarize today's new support tickets",
  "messages": [],
  "task_id": "task_xyz789",
  "mode": "auto",
  "flow_id": "flow_123",
  "async_callback_context": {
    "connection_id": "conn_abc",
    "customer_id": null,
    "trigger_source": "internal",
    "job_id": "job_456"
  }
}

Field	Required	Description
query	✅*	The user’s message. *If empty, it is taken from the last user message in messages.
messages	❌	Conversation history ([{role, content}]).
task_id	✅	Task/thread ID. If the task does not exist it is created (new tasks need flow_id).
run_id	❌	Provide to set the run ID; auto-generated if omitted.
mode	❌	auto, fast, or deep (default: auto).
flow_id	❌	Flow ID for identity resolution — required when creating a new task.
async_callback_context	✅	Where/how to deliver the result (see below).
max_steps	❌	Max agent steps (default: 10).
timeout_seconds	❌	Custom timeout.
attachments	❌	File attachments with presigned URLs.

async_callback_context:

Field	Required	Description
connection_id	✅	External connection ID for callback delivery.
customer_id	❌	Customer identifier. null for internal/manual flows (identity comes from the JWT).
trigger_source	❌	Source that triggered the run (e.g. telegram, internal). Default unknown.
job_id	❌	External job-tracking ID.
metadata	❌	Arbitrary passthrough (chat_id, etc.).

Response — 202 Accepted

{
  "id": "run_abc123",
  "task_id": "task_xyz789",
  "status": "accepted",
  "execution_mode": "fast",
  "routing_reason": "Customer-facing agent → fast",
  "message": "Request accepted for processing"
}

The final agent result is not in this response — it is delivered to your SQS callback. To observe progress in-band, use the following endpoints.

---

Following a background run

These work for any background run, whether started via /api/run/async or /api/run with stream: false.

GET /api/run/{task_id}/status

Is there an active run for this task, and what’s its progress? Used by clients to decide whether to reconnect after a refresh.

{
  "active": true,
  "run_id": "run_abc",
  "status": "running",
  "progress": {
    "tools_count": 2,
    "thoughts_count": 5,
    "has_content": true,
    "content": "…partial answer…",
    "started_at": "2026-07-03T12:00:00Z",
    "agent_mode": "deep"
  }
}

status may be running, pending, cancelling, complete, or error. When nothing is active you get {"active": false}.

GET /api/run/{task_id}/reconnect

Reconnect to an in-progress or recently completed run. Behaves in three ways:

• Active run → returns current state and an SSE stream of the remaining events.
• Pending run (worker not started yet) → returns an SSE stream that waits, then streams.
• Complete run → returns the final state as JSON.
• No run → 404.

Supports resuming from a cursor: send the standard Last-Event-ID header (what a browser EventSource sends automatically on reconnect), or the last_event_id query param for hand-built clients.

GET /api/tasks/{task_id}/stream

SSE stream of the task’s live events (same AG-UI event types as POST /api/run). See Tasks & Runs.

GET /api/runs/{run_id}/events

Paginated JSON history of a run’s events (durable). Good for polling clients that can’t hold an SSE connection. See Tasks & Runs.

---

Choosing an approach

• Interactive UI, may refresh → POST /api/run (stream: true), or stream: false then GET /api/run/{task_id}/reconnect.
• Webhook / worker, result delivered out-of-band → POST /api/run/async.
• Polling without SSE → GET /api/runs/{run_id}/events with cursor.

See also the Errors & rate limits reference.