> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events & streaming

> The resumable, sequence-keyed event stream behind every session.

Everything an agent does is recorded as an ordered stream of events. Each event has a monotonically increasing `seq` within its session, so the stream is fully resumable: reconnect from the last `seq` you saw and never miss or duplicate an event.

Because every event is sequence-keyed, a dropped connection is not a lost event — you reconnect with the last `seq` you handled and the stream picks up exactly where you left off:

```
   session events, ordered by seq
   ──▶ 125 ─ 126 ─ 127 ─ 128 ─ 129 ─▶ (live tail)
                             ▲
        reconnect with from_seq = last seq you handled
        replay from 0 for a fresh consumer · no gaps, no duplicates
```

## Event shape

Events follow a `{domain}.{action}` naming scheme.

```json theme={"system"}
{
  "seq": 128,
  "session_id": "ses_01H...",
  "type": "tool.completed",
  "created_at": "2026-08-20T23:14:02.140Z",
  "data": { "name": "bash", "exit_code": 0, "duration_ms": 812 }
}
```

## Streaming

Streams are delivered as Server-Sent Events. Pass a `from_seq` to replay from a point in history — new consumers pass `0` to get the whole session.

<CodeGroup>
  ```bash CLI theme={"system"}
  # Stream live; append new events as they arrive
  vetta session stream --session $SID --from-seq 0
  ```

  ```typescript TypeScript theme={"system"}
  for await (const e of session.stream({ fromSeq: lastSeq })) {
    lastSeq = e.seq;
    handle(e);
  }
  ```

  ```bash cURL theme={"system"}
  curl -N "https://api.vetta.sh/v1/sessions/$SID/events?from_seq=0" \
    -H "authorization: Bearer $VETTA_API_KEY" \
    -H "accept: text/event-stream"
  ```
</CodeGroup>

## Reading history

Events are also available as a paginated list for auditing or replay without a live connection.

```bash CLI theme={"system"}
vetta session events --session $SID --limit 100
```

## Sending events in

You drive a session by sending events too — a user message, a tool confirmation, or an interrupt.

```typescript TypeScript theme={"system"}
await session.send("Refund order #4821");          // user.message
await session.confirm(toolCallId);                  // tool.confirm  (ask-policy confirmation)
await vetta.sessions.interrupt(session.id);         // session.interrupt
```

## Common event types

| Type                | Meaning                                                                                                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session.running`   | The agent started a turn.                                                                                                                                                                                   |
| `session.idle`      | The turn yielded control and the session is waiting. Carries a `stop_reason`.                                                                                                                               |
| `session.completed` | The agent declared the task done.                                                                                                                                                                           |
| `session.usage`     | A cumulative cost/usage snapshot (`token_usage`, `consumed_micro_usd`, `active_seconds`, `tool_calls`), emitted before every idle or terminal transition. See [Observability](/docs/capabilities/observability). |
| `message.delta`     | A chunk of assistant text.                                                                                                                                                                                  |
| `message.completed` | An assistant message finished.                                                                                                                                                                              |
| `tool.started`      | A tool call began.                                                                                                                                                                                          |
| `tool.confirm`      | A tool gated by an [`ask` policy](/docs/concepts/policies) is waiting on your allow/deny.                                                                                                                        |
| `tool.completed`    | A tool call finished (success or error).                                                                                                                                                                    |
| `budget.exceeded`   | A call was refused because it would breach the cap.                                                                                                                                                         |
| `budget.paused`     | The session paused at its budget cap.                                                                                                                                                                       |

See the full list in the [Event reference](/docs/api/events).

<Card title="Next: completion window" icon="gauge" href="/docs/concepts/completion-window">
  Three prices for one model.
</Card>