---
title: "Search conversations"
method: GET
path: "/v1/inbox/conversations/search"
tags: ["Messages"]
---

# Search conversations

`GET /v1/inbox/conversations/search`

Search your conversations two ways at once, and get back the matching conversations, most-recent match first:

- Message text: matches words inside message bodies. Case-insensitive and accent-insensitive, exact tokens only (no substrings, no stemming). Each hit carries up to 3 most-recent matching messages. With direction=outgoing you can collect examples of how you write to customers, for example to teach an AI agent your tone of voice.
- Contact identity: matches the participant's name, username, or phone number as a case-insensitive substring. These hits have matchCount 0 and an empty matches array.

A conversation that matches both ways is returned once, carrying its message matches.

Only platforms whose messages are stored by Zernio are searchable: WhatsApp, SMS, Telegram, Facebook, Instagram, Twitter/X and Reddit. Bluesky conversations are fetched live from the platform and cannot be searched; those accounts are listed in meta.accountsSkipped.

## Query parameters

- `query` string, required
- `direction` 'incoming' | 'outgoing'
- `profileId` string
- `platform` 'facebook' | 'instagram' | 'telegram' | 'whatsapp' | 'sms' | 'slack'
- `accountId` string
- `limit` integer
- `cursor` string

## Response `200`

Conversations containing the query, most recent match first

- object
  - `data` object[]
    - `conversation` object
      - `id` string — Conversation ID, usable with the conversation messages endpoints
      - `platform` string
      - `accountId` string
      - `participantName` string, nullable
      - `participantUsername` string, nullable
      - `participantPicture` string, nullable
      - `status` 'active' | 'archived'
      - `lastMessage` string, nullable — The conversation's most recent message preview
      - `lastMessageAt` string, date-time, nullable
    - `matchCount` integer — Number of matching messages in this conversation. 0 when the conversation matched only on contact identity (name, username, or phone number), not on message text.
    - `matches` object[] — Up to 3 most-recent matching messages (empty for an identity-only match)
      - `id` string
      - `text` string, nullable
      - `direction` 'incoming' | 'outgoing'
      - `timestamp` string, date-time
  - `pagination` object
    - `hasMore` boolean
    - `nextCursor` string, nullable
  - `meta` object
    - `accountsQueried` integer
    - `accountsFailed` integer
    - `failedAccounts` object[]
      - `accountId` string
      - `accountUsername` string, nullable
      - `platform` string
      - `error` string
    - `lastUpdated` string, date-time
    - `accountsSkipped` object[] — Connected messaging accounts that cannot be searched (live-fetched platforms)
      - `accountId` string
      - `platform` string

## Other responses

- `400` — Invalid query, unsupported platform, or malformed cursor
- `401` — Unauthorized
- `403` — Inbox addon required

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/a23bb6e63438/schema)