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

# Threads SDK

> Cloud conversation history and live streaming with `rt.threads`

A thread is a durable conversation — every agent run writes into one, and the same thread is shared across clients (a run started from the dashboard, CLI, SDK, or a device all land in the same place). Most runs create threads for you ([Agents](/sdk/agents)); `rt.threads` is how you read that history, manage it, and stream it live.

## Read history

```typescript theme={null}
const { threads } = await rt.threads.list({ limit: 20 });

// A snapshot: thread metadata + its durable events
const snapshot = await rt.threads.get(threadId);
console.log(snapshot.thread.title, snapshot.events?.length);

// Just the events, paginated
const { events, hasMore, nextCursor } = await rt.threads.getEvents(threadId, { limit: 100 });

// Each run appends a rollout to the thread
const { rollouts } = await rt.threads.listRollouts(threadId);
```

`get()` reports `view: 'owner' | 'metadata_only'` — a non-owner with metadata access gets the summary without event bodies.

## Manage

```typescript theme={null}
await rt.threads.rename(threadId, 'Auth refactor');
await rt.threads.archive(threadId);
await rt.threads.compact(threadId);   // summarize older turns to reclaim context
await rt.threads.delete(threadId);    // permanent

const { events } = await rt.threads.activity(threadId, { limit: 50 });
```

## Live updates

Both subscriptions return an unsubscribe function. Use **`subscribe`** for durable frames — user/assistant messages, tool calls, run lifecycle — which is what you want for a history view or thread list:

```typescript theme={null}
const unsubscribe = rt.threads.subscribe(threadId, (frame) => {
  console.log(frame.type, frame);
});
// later: unsubscribe();
```

Use **`subscribeStreaming`** when you're rendering a live run and want token-by-token deltas:

```typescript theme={null}
const stop = rt.threads.subscribeStreaming(threadId, {
  onMessageDelta: (f) => process.stdout.write(f.delta),
  onThinkingDelta: (f) => {/* reasoning tokens: f.delta */},
  onToolCallStarted: (f) => console.log('tool:', f.toolName),
  onToolOutputDelta: (f) => {/* streamed tool output: f.delta on f.stream */},
  onMessageComplete: (f) => console.log('\n[done]', f.message.id),
  onRunCompleted: () => stop(),
  onError: (f) => console.error(f.code, f.message),
});
```

Token, reasoning, source, and tool-output deltas are **live-only** — they stream over the WebSocket but aren't written to durable history. Final messages, tool calls, and tool results are durable and replay through `getEvents()`.

## Methods

| Method                             | Description                                              |
| ---------------------------------- | -------------------------------------------------------- |
| `list(options?)`                   | List threads (`{ limit?, cursor?, archived?, allOrg? }`) |
| `get(id, options?)`                | Snapshot: thread + durable events                        |
| `getEvents(id, options?)`          | Paginated durable events                                 |
| `listRollouts(id)`                 | Per-run rollout metadata                                 |
| `rename(id, title)`                | Rename a thread                                          |
| `archive(id)`                      | Archive a thread                                         |
| `compact(id)`                      | Compact older turns                                      |
| `delete(id)`                       | Delete permanently                                       |
| `activity(id, options?)`           | Thread activity events                                   |
| `subscribe(id, cb)`                | Live **durable** frames → unsubscribe fn                 |
| `subscribeStreaming(id, handlers)` | Live **deltas** + lifecycle → unsubscribe fn             |

For the underlying REST + WebSocket surface, see the [Threads API](/api-reference/threads).