---
title: Events
description: The event envelope and every event type in task streams, swarm
  streams and webhook deliveries.
url: https://hexelstudio.com/docs/harness/events
---

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](https://hexelstudio.com/docs/harness/tasks#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](https://hexelstudio.com/docs/harness/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](https://hexelstudio.com/docs/harness/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](https://hexelstudio.com/docs/harness/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](https://hexelstudio.com/docs/harness/agents#promotions-between-environments)). 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](https://hexelstudio.com/docs/harness/webhooks).
