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

# Streaming

> Follow a chat live while the bot works.

A bot's reply is not a single response. The bot runs, uses tools, posts progress and then a message. To follow along, subscribe to the chat's events.

## Two ways to read a chat

| You want | Use |
| - | - |
| The messages so far | `threads/messages`, paging back with `before` |
| Everything that happens from now on | `threads/subscribe` |

A simple integration can send with `threads/send` and then poll `threads/messages` until the run finishes. Use `threads/subscribe` when you want live progress.

## Subscribe

`threads/subscribe` takes the chat (a `botId`, `groupId` or `externalConversationId`) and a `cursor`. Pass `-1` to start from now, or the last `seq` you saw to resume without gaps. `threads/head` returns the current cursor.

The response is a stream of server-sent events. Each event carries one product event in the same `json` envelope:

```json theme={null}
{
  "id": "...",
  "threadId": "...",
  "botId": "...",
  "seq": 42,
  "type": "run.completed",
  "runId": "...",
  "createdAt": "2026-11-05T09:30:00.000Z",
  "payload": { }
}
```

With the TypeScript client, a stream is an async iterator:

```ts theme={null}
const events = await cadence.threads.subscribe({ botId, cursor: -1 });
for await (const event of events) {
  if (event.type === "thread.message.created") console.log(event.payload);
  if (event.type === "run.completed") break;
}
```

## Event types you will see most

| Type | When |
| - | - |
| `thread.message.created` | A new message from a person, a bot or the system. |
| `thread.message.updated` | A message changed, for example while a reply is still being written. |
| `thread.progress` | The bot reports what it is doing. |
| `thread.ask` | The bot asks a question or needs an approval. Answer with `threads/answer`. |
| `run.started` | The bot started working. |
| `run.waiting_input` | The bot is paused until someone answers. |
| `run.completed`, `run.failed`, `run.cancelled` | The run ended. |
| `computer.status` | The bot's computer started, stopped or changed state. |

Other types exist (routines, skills, memory, usage). Ignore the ones you do not need. New types may be added, so do not fail on an unknown one.

## Resuming

Keep the highest `seq` you have processed. If the connection drops, subscribe again with that value as `cursor` and you receive only what you missed.


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