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

# Threads

> One conversation, and its full log.

A thread is one conversation (or one run) owned by an [agent](/model/agents).
Inside it, a **turn** is one admitted input plus all the work it sets off, and
an **event** is one permanent entry in the log. Threads never cross agents, and
an agent's threads can't read each other.

A message is an ordered `content` array of `text` and `image` blocks rather
than a plain string. That's what `POST /v1/agents/{agentId}/threads` takes to
create a thread and admit its first turn. Two optional fields can ride along:
`maxCost` caps what the whole thread may spend, and `model` pins the turn to
one exact catalog ID.

To send more input, `POST /v1/threads/{threadId}/messages`. The `mode` field
says what to do about work already running: `queue` waits its turn, `steer`
redirects the turn in flight, and `interrupt` stops it and goes now.
`POST .../cancel` drops active and queued work but keeps the history.

There are two ways to watch progress. The event log is the source of truth,
complete and replayable and paginated by cursor. The SSE streams are
best-effort and meant for keeping a UI live. When correctness matters,
reconnect and read the log.

An agent can also kick off side work with `thread.create` and wait on it with
`thread.wait`. Each sibling thread gets a fresh transcript and context window
under the same agent.

<Info>
  **Belongs to** one agent · **Has many** turns → events · **Status** is `running`
  \| `awaiting` | `idle` | `failed` | `cancelled`
</Info>

## Rules

* Each admitted turn freezes its configuration. See
  [How it fits together](/model/how-it-fits-together#what-a-turn-freezes).
* Sibling threads share memory and credentials, not transcripts.

## API

* Event types, statuses, modes, block limits: [Thread events](/reference/thread-events).
* `GET /v1/threads?state=waiting` for everything parked on a human.


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