Stream task events

Do this when you want to render or follow a run as it happens. Do not build a polling loop against GET /v1/workspaces/{workspace}/agents/{agent_id}/tasks/{task_id} for this — the stream already replays everything from the beginning, so attaching late loses nothing.

Prerequisites

A task id and its agent id. See Start a task.
An API key.
A client that can hold an open HTTP response. curl -N works; curl without -N buffers and looks hung.

Choose an endpoint

Option	Pick it when
`GET /v1/workspaces/{workspace}/agents/{agent_id}/tasks/{task_id}/events/stream`	You want live updates. Replays full history, then tails. Ends on a terminal event.
`GET /v1/workspaces/{workspace}/agents/{agent_id}/tasks/{task_id}/events`	You want a finished task’s history, paginated, in one request.
`POST /v1/workspaces/{workspace}/agents/{agent_id}/tasks/`	You are starting the task anyway and want the stream on the same connection. It ends at the first turn’s terminal event; add `?follow=true` to keep it through the follow-up window.

Steps

Stream live

curl -N "$AGENTAREA_URL/v1/workspaces/$WORKSPACE/agents/$AGENT_ID/tasks/$TASK_ID/events/stream" \
  -H "Authorization: Bearer $AGENTAREA_TOKEN" \
  -H "Accept: text/event-stream"

Each frame is a standard SSE event. The SSE event name and the payload’s event_type are the same dotted string, so a consumer can key on either:

event: connected
data: {"task_id": "3f2a...", "agent_id": "9b1d...", "execution_id": "task-3f2a...", "message": "Connected to task event stream", "timestamp": "2026-07-29T10:15:04.881233+00:00"}

event: llm.call.started
data: {"event_type": "llm.call.started", "event_id": "0f7c...", "timestamp": "...", "data": {"task_id": "3f2a...", "execution_id": "task-3f2a...", "iteration": 1}}

event: tool.call
data: {"event_type": "tool.call", "event_id": "1a2b...", "timestamp": "...", "data": {"tool_call_id": "call_abc", "tool_name": "bash", ...}}

event: task.completed
data: {"event_type": "task.completed", "event_id": "9e8d...", "timestamp": "...", "data": {"success": true, "message": "...", "validation_state": "passed"}}

The feed replays the task’s full durable history first, then tails live events, de-duplicating by event_id across the hand-off. It closes after task.completed, task.failed, or task.cancelled, except a task.completed whose data.execution_status is waiting: the task is waiting for a follow-up, and this endpoint keeps streaming its next turns.

Know where the stream you start a task with ends

POST .../tasks/ streams the run it starts and ends at that turn’s terminal event, waiting or not, so a request does not hold a connection for the 30-minute follow-up window. Send a follow-up with POST .../tasks/{task_id}/command (queue_message) and read their turns from GET .../tasks/{task_id}/events/stream (reconnect with Last-Event-ID to skip what you have). POST .../tasks/?follow=true keeps the old behaviour: the stream stays open through follow-up turns until the run finishes or 30 minutes pass.

Drop token-level chunks

llm.call.chunk events are high volume — one per token. They are included by default. Turn them off when you only need structural progress:

curl -N "$AGENTAREA_URL/v1/workspaces/$WORKSPACE/agents/$AGENT_ID/tasks/$TASK_ID/events/stream?include_chunks=false" \
  -H "Authorization: Bearer $AGENTAREA_TOKEN"

Read history instead

curl -s "$AGENTAREA_URL/v1/workspaces/$WORKSPACE/agents/$AGENT_ID/tasks/$TASK_ID/events?page=1&page_size=50" \
  -H "Authorization: Bearer $AGENTAREA_TOKEN" | jq '{total, has_next, first: .events[0]}'

{
  "total": 42,
  "has_next": false,
  "first": {
    "id": "0f7c...",
    "task_id": "3f2a...",
    "agent_id": "9b1d...",
    "execution_id": "task-3f2a...",
    "timestamp": "2026-07-29T10:15:04.912004+00:00",
    "event_type": "task.started",
    "event_id": "0f7c...",
    "message": "",
    "data": {"task_id": "3f2a...", "execution_id": "task-3f2a..."},
    "metadata": {"task_id": "3f2a...", "execution_id": "task-3f2a..."}
  }
}

A paged event and a live frame carry the same fields in the same places: event_type, event_id, timestamp and the payload under data, shaped the same way. id equals event_id. metadata is a deprecated alias holding the stored payload before the live stream’s flattening of nested data/original_data; read data.Filter with ?event_type=tool.call. Chunks never appear here — they are stream-only and are not persisted.

Write the consumer correctly

Two rules keep a consumer from breaking when the vocabulary grows:

Do not switch on every event name. Pass unknown types through. New event types are added without a version bump.
Only three types are terminal: task.completed, task.failed, task.cancelled. Stop on those and nothing else.

To collapse a model call or a tool call into one UI element rather than four lines, group by part id: tool_call_id for tool events, {execution_id}:{iteration} for LLM events. A later event with the same part id replaces the earlier one.

Verify

Confirm the stream terminates on its own with a terminal event rather than hanging:

curl -N -s "$AGENTAREA_URL/v1/workspaces/$WORKSPACE/agents/$AGENT_ID/tasks/$TASK_ID/events/stream?include_chunks=false" \
  -H "Authorization: Bearer $AGENTAREA_TOKEN" | grep -m1 -E '^event: task\.(completed|failed|cancelled)'

event: task.completed

The command exits as soon as the terminal frame arrives. If it exits with no output, the task produced no terminal event within the feed’s limits — see below.

Troubleshooting

The connection opens and nothing appears

Without -N , curl buffers the response. Add -N . If frames still do not arrive, confirm the task actually dispatched: a task with execution_id: null never started a workflow and will never emit events.

The stream closes after about 30 minutes with no terminal event

The feed has a 30-minute wall-clock limit so a stuck task does not tail forever. This is the feed giving up, not the task ending. Re-attach, or check GET .../tasks/{task_id} for the current status.

A completed task streams its history and then hangs briefly before closing

Expected. The reader replays from the database, then attaches to the live tail and waits for a terminal event it may have already replayed. It closes on the replayed terminal event.

Events are missing from history but were seen live

The event was published to the live stream but its database write failed; that failure is recorded and does not retry. The live tail is also best-effort in the other direction — a failed publish leaves the event in history only. History is the durable copy; prefer GET .../events when completeness matters.

A blocked task never emits task.blocked

There is no such event type. A blocked task emits task.failed on the feed while its row reads blocked . Read failure_reason from the task to tell them apart.

Events

The one dotted event vocabulary AgentArea emits, the two delivery paths behind it

Debug a failed task

Read the failure code, narrow it with the task rollup

Start a task

Launch an agent run over REST, the CLI, or A2A

Start here

Concepts

Guides

Self-host

Reference

API reference

API endpoints

Community

Stream task events

Prerequisites

Choose an endpoint

Steps

Stream live

Know where the stream you start a task with ends

Drop token-level chunks

Read history instead

Write the consumer correctly

Verify

Troubleshooting

Events

Debug a failed task

Start a task

​Prerequisites

​Choose an endpoint

​Steps

Stream live

Know where the stream you start a task with ends

Drop token-level chunks

Read history instead

Write the consumer correctly

​Verify

​Troubleshooting

​Related

Events

Debug a failed task

Start a task

Prerequisites

Choose an endpoint

Steps

Verify

Troubleshooting

Related