List conversations

GET

conversations

List conversations

curl --request GET \
  --url https://api.getarbol.com/v1/conversations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getarbol.com/v1/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "channelKind": "voice",
      "closeReason": "completed",
      "contactId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "direction": "inbound",
      "durationSeconds": 4503599627370495,
      "endedAt": "2026-08-29T14:30:00Z",
      "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "language": "<string>",
      "lastMessageAt": "2026-08-29T14:30:00Z",
      "messageCount": 4503599627370495,
      "originKind": "manual",
      "outcome": "success",
      "sentiment": "neutral",
      "startedAt": "2026-08-29T14:30:00Z",
      "status": "open",
      "summary": "<string>",
      "title": "<string>",
      "contactName": "<string>",
      "contactPhone": "<string>",
      "hasRecording": true
    }
  ],
  "nextCursor": "<string>",
  "total": 4503599627370495
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "code": "custom",
        "message": "<string>",
        "path": [
          "<string>"
        ]
      }
    ],
    "truncated": true
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "<string>",
  "data": {
    "missingPermissions": [
      "agents:read"
    ]
  }
}

Authorizations

Authorization

string

header

required

Organization-scoped Auth0 user access token issued to an approved first-party client or exchanged by a trusted OBO resource server.

Query Parameters

cursor

string

Opaque forward-only cursor returned as nextCursor by the previous page. Never construct one by hand.

Required string length: 1 - 4096

limit

integer

default:25

Page size; defaults to 25 and never exceeds 100.

Required range: 1 <= x <= 100

agentIds

string[]

Required array length: 1 - 50 elements

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

channelKinds

enum<string>[]

Required array length: 1 - 6 elements

Conversation transport family.

Available options:

voice,

whatsapp,

web

contactId

string

Opaque Arbol resource identifier; the endpoint and tenant-scoped lookup determine its resource type.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

direction

enum<string>

Direction of a Conversation relative to the organization.

Available options:

inbound,

outbound

Example:

"inbound"

factDefinitionId

string

With factKey: only Conversations whose current Fact under this Definition matches the key.

Maximum string length: 64

Pattern: ^[a-z][a-z0-9]{1,15}_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Example:

"agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31"

factKey

string

Option id, or true/false for a boolean Definition.

Required string length: 1 - 200

order

enum<string>

default:desc

Direction used by an explicitly selected resource sort.

Available options:

asc,

desc

Example:

"desc"

originKind

enum<string>

Source that created the Conversation record.

Available options:

inbound,

manual,

automation,

import,

test

Example:

"manual"

outcome

enum<string>

Success evaluation aggregated from the applicable Conversation assessment criteria.

Available options:

success,

failure,

unknown

Example:

"success"

string

Matches title, summary, the Contact's name, and its identity addresses.

Required string length: 1 - 200

Example:

"Marta Rojas"

sentiment

enum<string>

Coarse sentiment assigned to a Conversation.

Available options:

positive,

neutral,

negative

Example:

"neutral"

sort

enum<string>

default:startedAt

Stable sort field for Conversation collection pages.

Available options:

startedAt,

createdAt,

lastMessageAt,

durationSeconds,

messageCount

Example:

"startedAt"

startedAfter

string<date-time>

ISO 8601 timestamp with an explicit UTC offset.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

startedBefore

string<date-time>

Exclusive upper bound on startedAt.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Example:

"2026-08-29T14:30:00Z"

statuses

enum<string>[]

Required array length: 1 - 2 elements

Durable lifecycle state of a Conversation.

Available options:

open,

closed

Response

One page of Conversation summaries with the filtered total.

items

Conversation summary · object[]

required

Maximum array length: 100

Show child attributes

nextCursor

string | null

required

Opaque forward-only cursor returned as nextCursor by the previous page. Never construct one by hand.

Required string length: 1 - 4096

total

integer

required

Conversations matching the filters across every page.

Required range: 0 <= x <= 9007199254740991

List conversations

curl --request GET \
  --url https://api.getarbol.com/v1/conversations \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getarbol.com/v1/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "items": [
    {
      "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "channelKind": "voice",
      "closeReason": "completed",
      "contactId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "direction": "inbound",
      "durationSeconds": 4503599627370495,
      "endedAt": "2026-08-29T14:30:00Z",
      "id": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "language": "<string>",
      "lastMessageAt": "2026-08-29T14:30:00Z",
      "messageCount": 4503599627370495,
      "originKind": "manual",
      "outcome": "success",
      "sentiment": "neutral",
      "startedAt": "2026-08-29T14:30:00Z",
      "status": "open",
      "summary": "<string>",
      "title": "<string>",
      "contactName": "<string>",
      "contactPhone": "<string>",
      "hasRecording": true
    }
  ],
  "nextCursor": "<string>",
  "total": 4503599627370495
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "code": "custom",
        "message": "<string>",
        "path": [
          "<string>"
        ]
      }
    ],
    "truncated": true
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "defined": true,
  "inferable": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "<string>",
  "data": {
    "missingPermissions": [
      "agents:read"
    ]
  }
}

Overview

Endpoints

List conversations

Authorizations

Query Parameters

Response