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

# List direct message conversations

`GET /v1/inbox/conversations`

## Request

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

Returns the Instagram direct message threads PostZen holds for the accounts this key can reach, newest activity first, and refreshes that stored copy from the platform as a side effect (throttled per account, so a tight polling loop costs nothing extra). `meta` reports which accounts could not be refreshed; their stored threads are still returned. Read-only and read-write API keys are accepted.

## Query parameters

- `accountId` string
- `profileId` string
- `platform` 'instagram'
- `status` 'active' | 'archived'
- `sortOrder` 'asc' | 'desc'
- `limit` integer
- `cursor` string

## Response `200`

Conversations returned.

- InboxConversationsResponse
  - `data` InboxConversation[], required
    - `id` string, required: The platform's own conversation (thread) id. This is the `conversationId` every other conversation endpoint takes, not a PostZen document id.
    - `platform` 'instagram', required: Platform the thread lives on.
    - `accountId` string, required: PostZen account id the thread belongs to.
    - `accountUsername` string, required: Username of that connected account, so a multi-account list needs no second lookup.
    - `participantId` string: The other party's platform id (the IGSID on Instagram). Absent when the platform did not name the participant.
    - `participantName` string
    - `participantUsername` string
    - `participantPicture` string, uri
    - `participants` object[]: Every party on the thread, including the connected account itself. Present when the platform returned the participant edge.
      - `id` string, required
      - `name` string
      - `username` string
    - `lastMessage` string: Text of the most recent message PostZen has synced, when the platform reported one cheaply.
    - `lastMessageAt` string, date-time
    - `updatedTime` string, date-time, required: The platform's own last-activity time for the thread. This is the list sort key.
    - `status` 'active' | 'archived', required: PostZen-local state. Meta has no archive API, so archiving affects PostZen only and is never overwritten by a sync.
    - `unreadCount` integer, required: Incoming messages newer than the local read watermark. Marking the thread read sets it to 0 and a later sync cannot resurrect a stale count.
    - `url` string, uri: Deep link into the platform's own inbox, when the platform reports one. Instagram has no equivalent, so it is currently always absent.
  - `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)