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

# Thread & Run History

> Inspect agent thread history and customer activity

## Current Surfaces

RunTools exposes two customer-facing history surfaces today:

* **Thread history**: durable chat/run frames for agent conversations.
* **Customer activity**: resource-level operational events for sandboxes, workspaces, agents, threads, tools, installable agents, RunMesh, code execution, credentials, and billing usage.

The old audit replay API is not a current public SDK surface.

## Agent Threads

```typescript theme={null}
const first = await rt.agent.run('code-assistant', 'Inspect this repo.', {
  thread: true,
});

const detail = await rt.threads.get(first.threadId!);

for (const event of detail.events) {
  console.log(event.type, event.ts);
}
```

```bash theme={null}
curl "https://api.runtools.ai/v1/threads?limit=25" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

## Cloud Threads

For dashboard-style thread views, use `rt.threads`. Threads are backed by durable event history with rollups for listing and compaction.

```typescript theme={null}
const { threads } = await rt.threads.list({ limit: 25 });
const thread = await rt.threads.get(threads[0].id);
const events = await rt.threads.getEvents(threads[0].id);
```

Thread helpers also support append, archive, rename, compact, rollout listing, and streaming subscriptions.

```typescript theme={null}
const stream = await rt.threads.subscribe(thread.id, (frame) => {
  console.log(frame.type);
});

stream.close();
```

## Customer Activity

Use customer activity when you need an operational trail instead of replayable chat content. Activity events are sanitized before storage: raw prompts, command output, provider names, API keys, secrets, backend paths, and authorization material are not exposed.

```bash theme={null}
curl "https://api.runtools.ai/v1/activity?resource_type=sandbox&resource_id=$SANDBOX_ID&limit=50" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

Useful filters include `resource_type`, `resource_id`, `event_type`, `severity`, `status`, `thread_id`, `agent_run_id`, `sandbox_id`, `workspace_id`, `tool_slug`, `installable_agent_install_id`, `code_execution_id`, `runmesh_node_id`, `since`, `until`, `limit`, and `cursor`.

Thread-scoped activity is available under the thread API:

```bash theme={null}
curl "https://api.runtools.ai/v1/threads/$THREAD_ID/activity?limit=50" \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

Members see their own activity by default. Resource filters still require access to that resource. Org admins can view broader organization activity and filter by `actor_user_id`.

## What Is Not Public

There is no public `rt.runs.replay()`, `runtools runs replay`, or dashboard replay export flow in the current SDK/CLI. Use thread history and customer activity for debugging and operational history.