Events
The event envelope and every event type in task streams, swarm streams and webhook deliveries.
Every stream and webhook uses one envelope:
{
"id": "evt_...",
"seq": 1842,
"time": "2026-11-17T10:12:03.120Z",
"type": "tool.call",
"org_id": "org_...",
"workspace_id": "ws_...",
"environment_id": "env_...",
"task_id": "tsk_...",
"run_id": "run_...",
"data": {}
}seq increases within a task. id is unique: resume a stream after it with Last-Event-ID or ?after=, and use it to drop duplicate webhook deliveries.
Stored events carry metadata only. Content fields such as message text and tool arguments reach open streams live, in event.content chunks; see Content and history.
Task and run events
| Type | data |
|---|---|
task.state | {state, waiting_reason?, end_reason?} |
task.dependency | {waiting_on}: the tasks it waits for (Task chains) |
task.digest | {state, runs, steps, cost: {usd, tokens}, waiting_reason?, since}: a check-in |
task.erased | {scope: content | all, by: retention | request | zero_retention} |
run.started, run.ended | {version, attempt, end_reason?} |
run.forked | {parent_run_id, step, overrides} (Fork and replay) |
run.governance | What Titan's control plane knows of the run: {durable_session_id, control_session_id, state, lifecycle, end?} |
message.delta, message | {role, text}. message.delta is live text, never stored; message is not delivered to webhooks. |
tool.call, tool.result | {call_id, tool, args?, decision, result?, error?} |
approval.requested | {approval_id, call_id, tool, capability, decided_in: "titan"} |
approval.decided | {approval_id, call_id, status, approved} |
question.asked, question.answered | {question_id, prompt, answer?} |
sandbox.state | {sandbox, state} |
subagent.spawned | {child_run_id, agent} |
artifact.created | {artifact_id, name, size} |
cost.update | {usd, tokens_in, tokens_out} |
model.usage | One model call: {model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, server_tool_calls?} |
memory.usage | One memory operation: {operation: recall | remember, count} |
trigger.fired | {trigger, routine_id, fire_id} (Triggers) |
event.content | One chunk of one content field, live only: {task_id, run_id, seq, type, field, json?, offset, text, final?, truncated?} |
Swarm events
On a swarm's stream (GET /harness/swarms/{id}/events):
| Type | data |
|---|---|
swarm.progress | {swarm_id, state, total, done, working, queued, failed, skipped, escalated, cancelled, cost_usd, budget_usd, summary}; a pipeline adds blocked and stages |
swarm.stage | A pipeline's stage: {stage, state, total, done} |
end | The swarm ended: {state} |
Agent events
| Type | data |
|---|---|
agent.promoted | {agent, from_env, to_env, channel, version, gate_results}. Webhooks only, with promotions on (Agents and versions). It has no task_id. |
Webhook deliveries
A webhook's data keeps only metadata fields: for example tool.call sends {call_id, tool, decision}, question.asked {question_id, call_id}, and artifact.created {artifact_id, size}. A left-out field is named in data.omitted. See Webhooks.