iAdvizeDocs

List a site's conversations

Returns the conversations run through this site's agents, newest first by creation time, with their context, feedback, engagement and a summary of their labels. The list is scoped to the site in the path and to the organization of the API key. Filters combine with AND: `labels.all` needs every token, each `labels.any` group (tokens separated by `|`) needs one of its tokens, and `labels.none` excludes tokens and needs a positive label filter or a date range. `limit` is 1 to 100 (25 by default), and a cursor is bound to the filters it was issued for. Read-only: conversations are created by the agent, never via this API.

GET
/api/v1/sites/{siteId}/conversations

Authorization

ApiKeyAuth
AuthorizationBearer <token>

A WorkOS org-scoped API key, created from the dashboard's organization settings page. Identifies the tenant every read and write is scoped to. Missing, malformed, unknown, revoked, expired, or non-organization-owned keys all return 401 (no distinction, so the response can't be used to probe which keys or org ids exist).

In: header

Path Parameters

siteId*string

The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.

Query Parameters

from?string

Only conversations created at or after this time. ISO 8601 with an offset (Z or +02:00; encode a + as %2B).

Formatdate-time
to?string

Only conversations created before this time (exclusive). ISO 8601 with an offset.

Formatdate-time
channel?string

Only conversations of this channel.

Value in

  • "playground"
  • "hosted"
  • "web"
agentId?string

Only conversations run through this agent of the site (prefixed agt_).

language?string

Only conversations recorded in this language.

Value in

  • "fr"
  • "en"
  • "de"
  • "it"
  • "es"
  • "nl"
device?string

Only conversations started on this device. A conversation's device is the one recorded when the shopper started it. unknown covers an unidentified device and every conversation with no start record: all AI Storefront and test conversations, and older ones. Safari on iPadOS presents a desktop browser: those iPads are now detected and count as tablet, while iPad conversations started before the detection shipped (see the changelog) keep desktop.

Value in

  • "desktop"
  • "mobile"
  • "tablet"
  • "unknown"
feedback?string

Only conversations where the shopper gave at least one rating of that kind.

Value in

  • "positive"
  • "negative"
keywords?array<>

Repeatable, at most 20. Each term must appear in the conversation title, ignoring case. Every term must match.

Itemsitems <= 20
labels.all?array<>

Repeatable, at most 50. Every token must be present on the conversation. Tokens are key:value pairs listed by GET /api/v1/labels/vocabulary. See conversation labeling.

Itemsitems <= 50
labels.any?array<>

Repeatable, at most 20 groups. Each occurrence is one group of tokens separated by | (at most 50 tokens). A conversation matches a group when at least one of its tokens is present, and it must match every group.

Itemsitems <= 20
labels.none?array<>

Repeatable, at most 50. None of these tokens may be present. True/false labels only (key:true): filter a criterion by its explicit pass or fail. Needs labels.all, labels.any, from or to alongside it, otherwise the request is refused with invalid_filter.

Itemsitems <= 50
quality.min?number

Only conversations whose quality score is at least this value (0 to 1).

Range0 <= value <= 1
quality.max?number

Only conversations whose quality score is at most this value (0 to 1).

Range0 <= value <= 1
service.min?number

Only conversations whose service score is at least this value (0 to 1).

Range0 <= value <= 1
service.max?number

Only conversations whose service score is at most this value (0 to 1).

Range0 <= value <= 1
trust.min?number

Only conversations whose trust score is at least this value (0 to 1).

Range0 <= value <= 1
trust.max?number

Only conversations whose trust score is at most this value (0 to 1).

Range0 <= value <= 1
labelStatus?string

Only conversations in this label status. Cannot be combined with a label or score filter unless it is labeled.

Value in

  • "labeled"
  • "pending"
  • "failed"
  • "not_eligible"
openedFromStarter?string

true keeps the conversations the shopper opened from a conversation starter, false the others. Combined with the other filters by AND.

Value in

  • "true"
  • "false"
singleShopperMessage?string

true keeps the conversations with exactly one message from the shopper, false the others (none, or two and more). Counts the shopper's own messages, not the assistant's. Combined with the other filters by AND.

Value in

  • "true"
  • "false"
count?string

Set to true to add meta.count, the number of conversations matching the filters, capped at 10,000.

Default"false"

Value in

  • "true"
  • "false"
cursor?string

The meta.nextCursor of the previous page. Use it with the same filters it was issued for.

limit?integer

The page size, from 1 to 100.

Range1 <= value <= 100
Default25

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://example.com/api/v1/sites/string/conversations"
{  "data": [    {      "id": "conv_01kvnwmagvf27rc9cze5rm9e1r",      "title": "Looking for a waterproof jacket",      "channel": "web",      "language": "en",      "device": "mobile",      "createdAt": "2026-09-28T14:00:00.000Z",      "updatedAt": "2026-09-28T14:03:00.000Z",      "siteId": "site_01kvnwmagvf27rc9cze5rm9e1r",      "agentId": "agt_01kvnwmagvf27rc9cze5rm9e1r",      "agentName": "Storefront assistant",      "agentVersion": 2,      "agentVersionId": "agtv_01kvnwmagwf27rc9d7zef4qksf",      "entryWidget": {        "id": "ewgt_01kvnwmagvf27rc9cze5rm9e1r",        "name": "Product page launcher",        "format": "launcher",        "version": 3      },      "pageContext": {        "pageType": "category",        "productId": null,        "categoryName": "Jackets",        "pageUrl": "https://shop.example/collections/jackets"      },      "messageCount": 2,      "shopperMessageCount": 1,      "openedFromStarter": true,      "durationMs": 180000,      "feedback": {        "positive": 1,        "negative": 0      },      "productEngagement": {        "impressions": 1,        "clicks": 1      },      "labelStatus": "labeled",      "labelSummary": {        "resolution": "resolved",        "reviewReason": null,        "scores": {          "quality": 0.92,          "service": 1,          "trust": 1        },        "failedCriteria": []      }    },    {      "id": "conv_01kvnwmagwf27rc9d7zef4qksf",      "title": "Does this tent fit four people?",      "channel": "hosted",      "language": "en",      "device": "unknown",      "createdAt": "2026-09-27T09:12:00.000Z",      "updatedAt": "2026-09-27T09:20:00.000Z",      "siteId": "site_01kvnwmagvf27rc9cze5rm9e1r",      "agentId": "agt_01kvnwmagvf27rc9cze5rm9e1r",      "agentName": "Storefront assistant",      "agentVersion": 2,      "agentVersionId": "agtv_01kvnwmagwf27rc9d7zef4qksf",      "entryWidget": null,      "pageContext": null,      "messageCount": 6,      "shopperMessageCount": 3,      "openedFromStarter": false,      "durationMs": 480000,      "feedback": {        "positive": 0,        "negative": 1      },      "productEngagement": {        "impressions": 2,        "clicks": 0      },      "labelStatus": "pending",      "labelSummary": null    }  ],  "meta": {    "nextCursor": "eyJrIjpbIjIwMjYtMDktMjcgMDk6MTI6MDArMDAiXSwiaWQiOiJjb252XzAxa3Zud21hZ3dmMjdyYzlkN3plZjRxa3NmIiwiZCI6ImFmdGVyIiwiZiI6IjljMmE0ZjFlN2IzZDVhNjAifQ",    "count": {      "value": 128,      "capped": false    }  }}

Read the performance of a site's starter questions over a period

Returns the questions shown at least once in the period, with the figures the dashboard's Starter performance tab shows: impressions, clicks and click rate, in total and per surface, and the verdict against the site's own click rate. A question shown to nobody is not listed; `meta.notShownCount` counts them. The default order is the most shown first. Sorting by `rate` orders the whole result, and a cursor is bound to the period, the device and the sort it was issued for. `from` and `to` are required UTC days, at most 366 days apart.

Get a conversation with messages

Returns a single conversation: every field of the collection item, plus the playground `metadata` and the full ordered `messages` array. Read-only and tenant-scoped; messages have no API of their own. A conversation whose agent belongs to a different site than the one in the path, another organization's conversation and an unknown id all answer the same `404`.