# Conversation history — get_conversation_history

Read the current conversation in time order. The default returns messages only; request tool and artifact trace entries explicitly when you need them.

## Default result: messages

With no `entryTypes`, the tool returns only `message` entries in `entries[]`, ordered oldest-first within the page. Each message has `role`, `content` and `createdAt`. This default keeps tool/file trace data from crowding real conversation turns out of the page.

| Result field | Meaning |
| --- | --- |
| `conversationId` | The conversation bound to the run credential. |
| `entries` | The current page, ordered oldest-first. |
| `count` | Number of entries in this page. |
| `nextCursor` | Cursor to pass as `cursor` to fetch the next older page; `null` at the beginning. |
| `hasMore` | Whether older entries remain. |

## Include tools and files

Pass `entryTypes: ["message", "tool_call", "artifact"]` to receive the enriched stream. A `tool_call` is a redacted settled summary, never raw arguments/results. An `artifact` includes file metadata and `direction` (`uploaded` for user files, `delivered` for agent files), never a download URL.

> **Search is message-only:** `search` is a case-insensitive substring search over message content and requires at least two characters. It restricts results to `message` entries.

## How your agent reads older pages

History is paged newest-first. Your agent walks backwards through it on its own — the cursor is opaque and is only ever echoed back, never constructed.

1. Your agent calls the tool without `cursor` and gets the most recent page.
2. If `hasMore` is true, it passes the returned `nextCursor` back as `cursor`.
3. It repeats until `hasMore` is false.

## Who makes this call

Arguments are all optional: `limit` (defaults to 50, maximum 200), `cursor`, `entryTypes` and `search`.

### MCP

**Nothing for you to build.** Once your platform is pointed at ONBF's MCP server, your agent already has `get_conversation_history` in its tool list and does the calling itself, mid-run, whenever it decides to. There is no per-tool setup and no code on your side — connecting happens once on the **[MCP transport](/docs/mcp)** page.

### HTTP API

**Your backend makes this call**, at the moment your agent decides it needs `get_conversation_history`. The run credential from the webhook is the bearer token.

```bash
export ONBF_BASE="https://onbf.ai"
export ONBF_TOKEN="onbf_sess_FROM_WEBHOOK"

curl "$ONBF_BASE/api/passport/v1/tools/get_conversation_history" \
  -H "Authorization: Bearer $ONBF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"limit":50,"entryTypes":["message","tool_call","artifact"]}'
```

## Access

- **Scope:** `conversation:read`.
- **Credential:** run session only; personal tokens cannot read conversation history.
- **Bound:** the target conversation comes from the credential, never a request argument.