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

# Search direct message conversations

`GET /v1/inbox/conversations/search`

## Request

- Base URL: `https://api.postzen.dev`
- URL: `https://api.postzen.dev/v1/inbox/conversations/search`
- Auth: HTTP bearer

Searches the conversations PostZen has already synced — Meta exposes no message search API, so this reads PostZen's own copy and refreshes it first. Message text matches whole tokens, case- and accent-insensitively (`cafe` finds `café`, `art` does not match `start`); participant names and usernames match on substring. Setting `direction` narrows the search to message text only, so a thread that matched only on the participant's name is excluded. Read-only and read-write API keys are accepted.

## Query parameters

- `query` string, required
- `direction` 'incoming' | 'outgoing'
- `accountId` string
- `profileId` string
- `platform` 'instagram'
- `limit` integer
- `cursor` string

## Response `200`

Matching conversations returned.

- InboxConversationSearchResponse
  - `data` InboxConversationSearchHit[], required
    - `conversation` object, required
      - `id` string, required
      - `platform` 'instagram', required
      - `accountId` string, required
      - `participantName` string
      - `participantUsername` string
      - `participantPicture` string, uri
      - `status` 'active' | 'archived', required
      - `lastMessage` string
      - `lastMessageAt` string, date-time
    - `matchCount` integer, required: Matching messages in the thread. `matches` carries at most the first five of them; a thread matched only on the participant’s name reports 0.
    - `matches` InboxConversationSearchMatch[], required
      - `id` string, required: Platform message id of the matching message.
      - `text` string
      - `direction` 'incoming' | 'outgoing', required
      - `timestamp` string, date-time, required
  - `pagination` InboxDmPagination, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable, required: Pass back as `cursor` for the next page. `null` when the last page has been returned.
  - `meta` InboxDmMeta, required: How the read-through refresh went. A failure here is a failure to REFRESH, not to answer: the stored threads are still returned alongside it.
    - `accountsQueried` integer, required
    - `accountsFailed` integer, required
    - `failedAccounts` InboxDmFailedAccount[], required
      - `accountId` string, required
      - `accountUsername` string, required
      - `platform` 'instagram', required
      - `error` string, required: Why the refresh failed, in PostZen or the platform’s own words.
      - `code` string, required
      - `retryAfter` integer: Seconds the platform asked PostZen to wait, when it said.
    - `lastUpdated` string, date-time, required

## Other responses

- `400`: A parameter is missing or malformed — a plain `{ error }` body — or the account is not on a platform direct messages support (`platformUnsupported`).
- `401`: Missing or invalid API key.
- `403`: The account is outside the API key's profile access (`forbidden`), or the connection is missing the messaging scope this call needs (`platformCapabilityMissing`). Reconnect the account to grant it.
- `404`: No such account (`accountNotFound`) or no such conversation for that account (`conversationNotFound`).
- `424`: The connection needs to be reauthorized before its messages can be read (`connectionDead`).
- `429`: Rate limit exceeded. Retry after the interval indicated by the `Retry-After` header.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/postzen/apis/postzen-public-api.md) · [All operations](https://skmtc.dev/postzen/apis/postzen-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postzen/apis/postzen-public-api/revisions/40863e3710ec?raw)