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

```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"
```

## 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](https://vetta.sh/docs/capabilities/observability.md). |
| `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](https://vetta.sh/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](https://vetta.sh/docs/api/events.md).

> [card] [Next: completion window](https://vetta.sh/docs/concepts/completion-window.md)
>
> Three prices for one model.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.