---
title: "List conversations (v2)"
method: GET
path: "/api/v1/discovery/conversations-v2"
tags: ["discovery"]
---

# List conversations (v2)

`GET /api/v1/discovery/conversations-v2`

## Request

- Base URL: `https://point11.ai`
- URL: `https://point11.ai/api/v1/discovery/conversations-v2`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://auth.point11.ai/oauth2/authorize`, token URL `https://auth.point11.ai/oauth2/token`)

Page through every conversation of a campaign's results window (dated in the 30 days ending its as-of day, `scope.window`: the conversations its values count), newest or oldest first, optionally narrowed to segments, one assistant, the campaign brand's outcome (won; mentioned while another brand or none won; absent), and its matchup with one rival (`rival`: the conversations its win and loss reasons against that brand are counted from), and searched, ignoring case, by the customer's name and the transcript's text (the customer's prompts and the assistant's answers). Each row names the customer, the assistant, when it started, how many turns it shows, the outcome, the winner and the brands it named, its first prompt, where a search hit, and how many sources it cited. Read one transcript in full with business_customer_conversations_get_v2 (the row's conversationId as `id`, and its customerId). A campaign without results answers its state and no rows.

## Query parameters

- `limit` integer: Number of conversations to return (1–50)
- `cursor` string: Opaque cursor returned as nextCursor by the previous page
- `id` string, uuid, required: Discovery campaign id.
- `dateRange` string, nullable: Result window: `all`, a preset id, or `yyyy-MM-dd..yyyy-MM-dd`. Omit for the campaign's default window.
- `segments` string[]: Narrows the read to these segments, ANDed: one `axis:id` per axis (any number of distinct `customer:` entries), in canonical axis order. Empty reads the whole dispatch.
- `search` string: Text matched, ignoring case, against the customer's name and the transcript (prompts and answers).
- `engine` 'chatgpt' | 'gemini' | 'claude' | 'grok': Only this assistant's conversations.
- `outcome` 'won' | 'mentioned' | 'absent': Only conversations with this outcome for the campaign's brand.
- `conversationId` string, uuid: Only this conversation: its row when the window and segments hold it, else none, so a link to one conversation reads its row once.
- `sort` 'newest' | 'oldest': By when each conversation started; default newest first.
- `rival` string: Only the campaign brand's matchup with this brand: conversations that name both, where one of the two is the brand the conversation recommended, the conversations discovery.competitor-reasons.get counts its win and loss reasons against that brand from. Name it as those reasons do (`data.option.id`). With `outcome`, `won` keeps the campaign brand's wins and `mentioned` its losses to that brand.

## Headers

- `Point11-Organization` string, uuid

## Response `200`

Success.

- DiscoveryConversationsListV2Response
  - `data` object[], required
    - `conversationId` string, required: The Discovery conversation's id.
    - `customerId` string, required: The customer's id, which business.customer-conversations.get takes.
    - `customerKey` string, nullable, required: The customer's key in the customer pages.
    - `customerName` string, required
    - `customerSubtitle` string, required: The customer's job title, else their age; empty when neither is known.
    - `engine` string, required: The assistant's name, e.g. ChatGPT.
    - `engineId` string, required: The assistant's provider id, e.g. openai.
    - `occurredAt` string, required: ISO timestamp the conversation started.
    - `turnCount` integer, required: Turns the transcript shows.
    - `outcome` 'won' | 'mentioned' | 'absent', required: The campaign brand's outcome: `won`; `mentioned`, named while another brand or none won; `absent`, not named.
    - `winnerBrand` string, nullable, required: The brand the conversation recommended, if any.
    - `mentionedBrands` string[], required: The brands the conversation named, in the order the analysis recorded them, at most 12.
    - `mentionedBrandCount` integer, required: How many brands the conversation named in all.
    - `firstPrompt` string, required: The customer's first prompt on one line, shortened.
    - `match` object, nullable, required: Where a search hit; null without a search.
      - `field` 'customer' | 'prompt' | 'answer', required: Where the first hit is: the customer's name, a prompt, or an answer.
      - `turnIndex` integer, nullable, required: The hit's turn, counted from 0 in the turns business.customer-conversations.get returns; null for a hit in the customer's name.
      - `excerpt` string, required: The text around the hit, on one line.
      - `start` integer, required: Where the hit starts in `excerpt`, in UTF-16 code units.
      - `end` integer, required: Where the hit ends in `excerpt`, in UTF-16 code units.
    - `sourceCount` integer, required: Sources the answers cited.
  - `nextCursor` string, nullable, required
  - `scope` DiscoveryScope, required
    - `campaignId` string, required
    - `state` 'ready' | 'running' | 'failed' | 'out-of-range' | 'no-campaign', required: `ready` carries results; every other state carries none.
    - `failureReason` string, nullable, required
    - `perspective` object, nullable, required: The brand lens applied; null when the report honors no lens or carries no results.
      - `brand` string, required: The brand the results were read as.
      - `isOwnBrand` boolean, required: Whether that brand is the campaign's own.
    - `window` object, nullable, required: The results window; null unless `state` is `ready`.
      - `from` string, date, required: The first UTC day a trend plots: the range's, never before the first interaction.
      - `to` string, date, required: The last UTC day a trend plots: the range's end, never past today.
      - `asOf` string, date, required: The UTC day every single value is as of: its value is the average over the campaign's interactions dated in the 30 days ending with it. The range's end, or, when those 30 days hold none, the last day with an interaction.
      - `comparedTo` string, date, required: The day a change compares with: 30 days before asOf.
      - `interactionCount` integer, required: The interactions dated in the 30 days ending asOf, under the scope.
      - `customerCount` integer, required: The distinct customers of those interactions.
  - `totalCount` integer, nullable, required: Conversations the filters and search keep; null unless `scope.state` is `ready`.

## Other responses

- `400`: The input, query, or Idempotency-Key is invalid.
- `401`: The bearer is missing, expired, or not accepted.
- `403`: The credential lacks the operation's scope or role, or the operation needs a different door.
- `404`: The resource or organization does not exist for this caller.
- `405`: This path takes another HTTP method, named in `Allow`.
- `409`: The request conflicts with current state or with prior use of its Idempotency-Key.
- `413`: The request, or the answer it asks for, is too large; narrow it.
- `429`: The credential's rate budget is spent; retry after `Retry-After` seconds.
- `500`: An unexpected server failure; retry later. Only `request_id` identifies it.
- `503`: A dependency is temporarily unavailable; retry after `Retry-After` seconds.
- `default`: Another status a product answers for its own refusal (for example `415` for an unsupported attachment); branch on `code`.

---

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