Skip to content
Hexel StudioDocs

Events

The event envelope and every event type in task streams, swarm streams and webhook deliveries.

On this page

Every stream and webhook uses one envelope:

JSON
{
  "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

Typedata
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.governanceWhat 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.usageOne model call: {model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, server_tool_calls?}
memory.usageOne memory operation: {operation: recall | remember, count}
trigger.fired{trigger, routine_id, fire_id} (Triggers)
event.contentOne 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):

Typedata
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.stageA pipeline's stage: {stage, state, total, done}
endThe swarm ended: {state}

Agent events

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