---
title: "List Conversations"
method: GET
path: "/v2/conversations/"
tags: ["conversations"]
---

# List Conversations

`GET /v2/conversations/`

## Request

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

List conversations with optional filters and search.

NOTE: when no ``status`` filter is provided the default response hides
rows with ``status="FAILED"`` — these are audit-only pre-flight /
provider-rejected compose attempts. To see them, pass
``status=FAILED`` explicitly.

Each row adds ``ai_agent_name``, ``direction`` (who wrote first) and, in
``carrier_offers``, the latest offer with its rates, currency and load.

## Query parameters

- `workspace_id` string, required
- `status` string, nullable
- `load_id` string, nullable: Filter by the thread's TMS load: its own external_reference_load_id or its offers' load
- `label` string, nullable: Filter conversations that have this label
- `has_drafts` boolean, nullable: Only conversations with a draft message
- `has_sent` boolean, nullable: Only conversations that have outbound messages
- `is_starred` boolean, nullable: Only starred conversations
- `channel` string, nullable: Filter by channel: email | sms | whatsapp, or several comma-separated
- `q` string, nullable: Search the subject, participants, each message's sender and subject, and the carrier name, email and load of the thread's offers (case-insensitive)
- `search_body` boolean: Also search the plain-text message bodies with `q` (slower)
- `limit` integer
- `offset` integer
- `thread_direction` string, nullable: Who wrote first: all | inbound (the carrier) | outbound (us). When set, it replaces the legacy folder rule that the default view keeps only threads with a carrier message.
- `start_datetime` string, date-time, nullable: Last message at or after this instant
- `end_datetime_exclusive` string, date-time, nullable: Last message before this instant
- `ai_agent_id` string[], nullable: Only threads handled by one of these AI agents
- `outcome` string, nullable: The row's outcome pill: failed | ai_handling | booked | accepted | declined | negotiating | completed. The call-only outcomes (transferred, no_answer, stale, live, in_progress) match no thread.
- `filters_json` string, nullable: JSON array of record filters: [{"field": "carrier_id", "operator": "IN", "values": ["C-1"]}, {"field": "resource", "operator": "EQUALS", "resource_type": "Load", "identifier_field": "external_reference_id", "value": "484612"}, {"field": "load.origin_state", "operator": "IN", "values": ["TX"]}]. carrier_id and the load id match the thread's own reference or any of its offers'; a load id may be the TMS display reference. load.* fields are those Calls filters on, answered by the TMS for the 5,000 most recently active loads of the matching threads.

## Headers

- `mentium-workspace-id` string, nullable

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

## Changes

- **2026-11-04** `b4ed8e59432e`: 1 info
  - added the new optional `query` request parameter `search_body`

[Operation history](https://skmtc.dev/mentium/apis/mentium-api/changes/v2/conversations/get.md)

---

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