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

# List conversations

`GET /v1/conversations`

## Request

- Base URL: `https://api.cadencercs.com`
- URL: `https://api.cadencercs.com/v1/conversations`
- Auth: HTTP bearer

The measurement surface: each row carries the message counts and direction split that decide what it cost, so reply rate, completion and session-trigger rate are all computable from the public API. A brand-scoped key sees only its own brand, whatever it asks for.

## Query parameters

- `brandId` string
- `agentId` string
- `state` string
- `since` string
- `limit` integer

## Response `200`

Conversations, newest first.

- object
  - `conversations` Conversation[], required
    - `id` string, required
    - `agentId` string, required
    - `brandId` string, required
    - `to` string, required: Recipient, E.164.
    - `channel` 'rcs' | 'sms' | 'queued'
    - `channelConfidence` 'provisional' | 'committed': `provisional` means we chose a channel and have no confirmation yet. It becomes `committed` when the channel is proven: on the first delivery receipt from the handset on RCS, or on an SMS fallback **caused by the recipient** — no RCS on their device, or your agent not launched on their carrier. A fallback caused by *us* — a rejected payload, a bad credential, a timeout — leaves this `provisional`, because it says nothing about the recipient. Committing there would mark a perfectly reachable handset SMS-only for the rest of the conversation on the strength of our own bug, and report it as a fact about their phone. See `fellBack.ourFault` on the send response.
    - `trustLevel` 'verified_rcs' | 'branded_sms' | 'unbranded_sms'
    - `state` 'OPENING' | 'OPEN' | 'USER_REPLIED' | 'CHANNEL_FLIP_TO_SMS' | 'CLOSING' | 'CLOSED' | 'CLOSED_OPTOUT', required
    - `useCase` 'transactional' | 'promo' | 'conversational' | 'leadgen'
    - `turnCount` number
    - `turnCeiling` number
    - `rcsOnly` boolean: SMS is disabled for this conversation.
    - `createdAt` string
    - `closedAt` string, nullable
  - `count` number, required

## Other responses

- `401`: No usable session cookie, session token or API key.
- `500`: Unexpected server error. The body is always JSON.

---

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