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

# Thread events

> Every event type, status, and content block a thread can produce.

Read the durable log with `GET /v1/threads/{threadId}/events`. Every event
carries `seq`, `eventId`, `threadId`, `turnId`, `type`, and `occurredAt`.
Everything else depends on `type`.

## Event types

| Type | Written when | Also carries |
| - | - | - |
| `user_message` | An input is admitted into the thread. | `content`, `principal`, `submitMode` |
| `assistant_message` | The model produces a response. | `content`, `modelId`, `inReplyToSeq` |
| `tool_intent` | The model asks to call a tool, before it runs. | `toolName`, `toolInput`, `toolCallId`, `providerToolCallId`, `modelId` |
| `tool_result` | The tool returns. | `toolOutput`, `toolCallId`, `reveal`, `usage`, `timing`, and `failureCode` / `failureText` when it failed |
| `wait_created` | The turn parks on a client tool or a hook that decided `ask`. | `waitId`, `toolCallId`, `toolName`, `toolsetId`, `usage` |
| `wait_resolved` | Someone resolved that wait. | `waitId`, `waitResult`, `toolCallId`, `toolsetId` |
| `hook_decision` | Any hook finished evaluating. | `hook`, `toolCallId`, `waitId` |
| `turn_completed` | The turn finished normally. | `usage`, `principal` |
| `turn_cancelled` | The turn was cancelled before finishing. | `usage`, `principal` |
| `turn_failed` | The turn failed. | `failureCode`, `failureText`, `failureDetails`, `usage` |
| `compacting` | Context compaction started. | `compaction`, `modelId` |
| `compacted` | Compaction finished, successfully or not. | `compaction`, `modelId`, `usage`, `timing`, and `failureCode` / `failureText` when it failed |

If you see a `tool_intent` with no `tool_result` after it, that call is parked
on a wait.

`reveal` on a `tool_result` is how `tool_search` works: it names the tool
families and tools that result made callable for the rest of the thread.

## Compaction

`compacting` and `compacted` both carry a `compaction` object:

| Field | Meaning |
| - | - |
| `throughSeq` | Boundary being summarized; every event at or below it is folded in. |
| `attempt` | Round within one sample, such as `build:0` or `overflow`. |
| `preview` | Bounded plain-text preview. Set only on a successful `compacted`. |

## Thread status

The thread record reports one coarse `status`:

| Status | Meaning |
| - | - |
| `running` | A turn is executing right now. |
| `awaiting` | Parked on an open wait (a client tool result or a hook approval). |
| `idle` | Nothing running, nothing queued. Ready for the next input. |
| `failed` | The last turn failed. |
| `cancelled` | The last turn was cancelled. |

`GET /v1/threads?state=waiting` is the one accepted filter on the thread list.
It gives you the queue of threads waiting on a person, and each thread summary
carries `pendingWaits`.

## Submit modes

`POST /v1/threads/{threadId}/messages` takes an optional `mode`:

| Mode | Behavior |
| - | - |
| `queue` | Default. Append behind whatever is running. |
| `steer` | Redirect the turn already in flight. `model` is not accepted with `steer`. |
| `interrupt` | Stop current work and admit this input now. |

## Content blocks

`content` is an ordered array of blocks, on both user and assistant messages:

| Block | Fields | Limits |
| - | - | - |
| `text` | `type`, `text` | Non-blank UTF-8. 8 KiB per user message, 64 KiB per assistant message. |
| `image` | `type`, `imageId` | An ID from `POST /v1/agents/{agentId}/images`. At most 20 per message, unique. |

One message holds at most 40 blocks and 512 KiB of encoded JSON.

## Streams

`GET /v1/threads/{threadId}/events/stream`,
`GET /v1/agents/{agentId}/events/stream`, and `GET /v1/events/stream` push
Server-Sent Events for one thread, one agent, or the whole workspace. They are
best-effort activity hints, not a replay log. Whenever correctness matters,
reconnect and read the durable log.


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