---
title: "List conversations"
method: POST
path: "/v1/actions/list_conversations"
tags: ["Messages"]
---

# List conversations

`POST /v1/actions/list_conversations`

## Request

- Base URL: `https://api.heyreagent.com`
- URL: `https://api.heyreagent.com/v1/actions/list_conversations`
- Auth: HTTP bearer

List the conversations in the stored copy of your inbox, across your accounts.

It reads what sync_inbox last stored, not LinkedIn itself; lastFetchedAt says how old that is. list_chats reads LinkedIn live.

To read or re-sync a row, pass its conversationUrl. To reply, pass its participantProfileUrl to send_message; that reaches a 1st-degree connection. For an InMail conversation, take the chatId from list_inmail and use send_chat_message.

readKey changes whenever the conversation's latest message changes: take it from a fresh call.

inbox[].headline comes back empty for the rows an inbox sync writes; the headline is in inbox[].raw.participantHeadline.

Pages are by page number, not by cursor.

Docs: https://heyreagent.com/docs/actions/list_conversations

## Request body

- object
  - `search` string: Search by participant, headline, message, or connection label.
  - `unreadOnly` boolean: Only return unread conversations.
  - `includeThreads` boolean: Attach the full message history (oldest→newest) to each conversation row under `thread`, resolved server-side — not just the latest message. Use this to read a specific conversation by searching the lead name.
  - `limit` number: Max conversations to return (default 50, max 200).
  - `page` number: Page number (default 1).

## Response `200`

It worked. Inside result: total, page, limit, totalPages, hasMore, lastFetchedAt, syncInProgress, inbox.

- Worked
  - `ok` true, required
  - `result` object, required: What was asked for. A field that does not apply is left out, or is null.

## Other responses

- `default`: It did not work. The message says why, in plain English.

---

[API](https://skmtc.dev/heyreagent/apis/heyreagent-api.md) · [All operations](https://skmtc.dev/heyreagent/apis/heyreagent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/heyreagent/apis/heyreagent-api/revisions/917360c5f841?raw)