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

# Get Conversations Tool

> List, read, and search chat conversations — your own, or org-wide for admins

## What it does

The Get Conversations tool lets agents work with conversation history on the platform: find past conversations, search across them, and read full transcripts. By default an agent sees only the conversations of the user it is working on behalf of; organization admins can widen the scope to every user's conversations in the org.

Because transcripts can be very large, the tool never returns them inline. The `get` action exports a conversation as a markdown file attachment, and the agent reads it in chunks with the [Read File](/tools/read_file) tool — so even multi-hour, tool-heavy threads can be reviewed without overwhelming the model's context. Enabling this tool automatically adds `read_file` to the agent.

## Key features

* **List and filter**: Browse conversations by agent, user (admin only), source (chat, scheduled task, email, voice), and date range
* **Full-text search**: Weighted search across conversation names and message content, with highlighted snippets
* **Chunked transcript reading**: Full transcripts — including tool calls and their inputs/outputs — exported as attachments and read page by page
* **Admin org-wide scope**: With `scope: "org"`, admins can review any user's conversations, with user attribution on every result
* **Safe by construction**: Images and large binary payloads are replaced with compact markers so transcripts stay small

## Parameters

| Parameter                   | Type    | Required     | Description                                                                                                                     |
| --------------------------- | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `action`                    | string  | Yes          | `"list"`, `"get"`, or `"search"`                                                                                                |
| `scope`                     | string  | No           | `"mine"` (default) — the current user's conversations. `"org"` — all users' conversations; requires the user to be an org admin |
| `thread_id`                 | string  | For `get`    | The conversation UUID to export. Find IDs via `list` or `search`                                                                |
| `query`                     | string  | For `search` | Full-text search query (plain words)                                                                                            |
| `agent_id`                  | integer | No           | Only conversations with this agent (`list` / `search`)                                                                          |
| `user_email`                | string  | No           | Only conversations belonging to this user — org scope only (`list` / `search`)                                                  |
| `source`                    | string  | No           | Only conversations from this source, e.g. `"chat"`, `"scheduled-task"`, `"agent-email"`, `"mcp"`, `"retell-call"` (`list`)      |
| `from` / `to`               | string  | No           | ISO 8601 date bounds on conversation creation (`list` / `search`)                                                               |
| `limit`                     | integer | No           | Max results, default 20, max 100 (`list` / `search`)                                                                            |
| `offset`                    | integer | No           | Pagination offset (`list`)                                                                                                      |
| `include_sub_conversations` | boolean | No           | Include conversations spawned by agent-to-agent calls (default false) (`list`)                                                  |

<Note>
  **Org-wide scope is verified, not configured.** `scope: "org"` checks the requesting user's *current* role in Clerk on every call — it works for real org admins only, including in scheduled tasks and agent-to-agent calls, and cannot be enabled for non-admins. Admins can additionally hard-disable org scope on a specific agent by setting `orgWideAccess: false` in the tool's config.
</Note>

## Common use cases

### Reviewing how an agent performed

*"Pull up my last conversation with the Deal Screener and summarize what it concluded"*

The agent finds the thread, exports the transcript, and reads through it — including every tool call the other agent made.

### Org usage pulse checks (admins)

*"How is the team actually using our agents this week? Review a few recent conversations and tell me what's working"*

With org scope, the agent lists recent conversations across all users, picks representative threads, and reports on usage patterns, agent quality, and stuck workflows.

### Improving agents from real conversations

*"Look at the last five conversations users had with the Support agent and suggest system-prompt improvements"*

Pairs naturally with [Manage Agents](/tools/manage_agents): review real transcripts, identify recurring corrections or failures, then update the agent's configuration.

### Checking on scheduled automations

*"Did the nightly dashboard refresh actually run correctly this week?"*

Filter by `source: "scheduled-task"`, export a run's transcript, and verify what the automation actually did — not just whether it reported success.

## Reading exported transcripts

The `get` action returns a short preview plus a file attachment named `conversation_<id>.md`. Read it with the Read File tool:

```text theme={null}
read_file with path "attachment:conversation_0f292832-71b.md"
```

Read File returns \~2,000 lines per call; pass `offset` (a 1-based line number) to continue through longer transcripts. The transcript header includes the conversation's metadata, token totals, and any sub-conversations spawned from it, which can be exported with further `get` calls.

## Security

* Non-admins can never see other users' conversations — not by thread ID, not via filters. Requests for another user's thread return "not found."
* The org-admin check is a live lookup against the user's current role, so it cannot be spoofed through scheduled tasks or agent-to-agent hops, and access ends immediately when a user loses the admin role.
* Results in `mine` scope contain no other users' identity fields; org-scope results attribute each conversation to its user.
* System prompts are not included in exported transcripts.