---
title: "List Conversations"
method: GET
path: "/api/v1/inbox/conversations"
tags: ["inbox"]
---

# List Conversations

`GET /api/v1/inbox/conversations`

## Request

- Base URL: `https://api.nudgelink.co` (the document declares no server; this is the origin it was published from)
- URL: `https://api.nudgelink.co/api/v1/inbox/conversations`
- Auth: HTTP bearer

List conversations for the current client.

A conversation = one lead with at least one INBOUND message. Sorted
by last-message timestamp, newest first.

A6 unread semantics:
  * ``unread_total`` is GLOBAL (all conversations, not just this page).
  * ``unread_only=true`` filters in SQL BEFORE pagination — pages can
    no longer come back empty while unread conversations exist deeper.
  * ``total`` = all conversations normally; = unread conversations when
    ``unread_only`` is set.
Implementation: one query pulls every inbound (lead_id, created_at) for
the client, and the per-lead cursor comparison happens in Python. Exact,
single round-trip, and fine at pilot scale (inbound volume is small); at
~thousands of inbound rows move the cursor map to a real table and do the
anti-join in SQL (see plan A6 "real fix").

## Query parameters

- `limit` integer
- `offset` integer
- `unread_only` boolean

## Response `200`

Successful Response

- InboxConversationListResponse
  - `items` InboxConversationRow[], required
    - `lead_id` string, uuid, required
    - `name` string, required
    - `title` string, required
    - `company` string, required
    - `linkedin_url` string, required
    - `lead_status` string, required
    - `last_message_preview` string, required
    - `last_message_direction` string, required
    - `last_message_at` string, date-time, required
    - `unread_count` integer, required
    - `total_inbound` integer, required
    - `last_inbound_classification` string, nullable, required
  - `total` integer, required
  - `unread_total` integer, required

## Other responses

- `422`: Validation Error

---

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