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"
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"
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",      "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,      "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",      "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,      "durationMs": 480000,      "feedback": {        "positive": 0,        "negative": 1      },      "productEngagement": {        "impressions": 2,        "clicks": 0      },      "labelStatus": "pending",      "labelSummary": null    }  ],  "meta": {    "nextCursor": "eyJhdCI6IjIwMjYtMDktMjcgMDk6MTI6MDArMDAiLCJpZCI6ImNvbnZfMDFrdm53bWFnd2YyN3JjOWQ3emVmNHFrc2YiLCJmIjoiOWMyYTRmMWU3YjNkNWE2MCJ9",    "count": {      "value": 128,      "capped": false    }  }}

Change a version's status

Moves a version through its lifecycle. Only the `status` can change here: the instructions are immutable. Promoting a version to `champion` archives the agent's current champion automatically (at most one champion per agent).

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`.