Query analytics

POST

analytics

query

Query analytics

curl --request POST \
  --url https://api.getarbol.com/v1/analytics/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sections": [
    "summary",
    "chart"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({sections: ['summary', 'chart']})
};

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

import requests

url = "https://api.getarbol.com/v1/analytics/query"

payload = { "sections": ["summary", "chart"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "window": {
    "from": "2026-08-29T14:30:00Z",
    "granularity": "day",
    "timezone": "UTC",
    "to": "2026-08-29T14:30:00Z"
  },
  "agentPerformance": [
    {
      "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "averageDurationSeconds": 1,
      "conversations": 4503599627370495,
      "lastActiveAt": "2026-08-29T14:30:00Z",
      "name": "<string>",
      "successRate": 0.5
    }
  ],
  "chart": {
    "metric": "conversations",
    "points": [
      {
        "date": "<string>",
        "value": 123
      }
    ]
  },
  "statusBreakdown": [
    {
      "count": 4503599627370495,
      "key": "<string>"
    }
  ],
  "summary": {
    "averageDurationSeconds": 1,
    "contacts": 4503599627370495,
    "conversations": 4503599627370495,
    "messages": 4503599627370495,
    "successRate": 0.5
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "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"
    ]
  }
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

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.

Body

application/json

A bounded set of analytics projections over one shared half-open time window.

sections

enum<string>[]

required

Required array length: 1 - 4 elements

Typed projection requested from the analytics query.

Available options:

summary,

chart,

statusBreakdown,

agentPerformance

agentId

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"

channelKind

enum<string>

Conversation transport family.

Available options:

voice,

whatsapp,

telegram,

slack,

email,

web

Example:

"voice"

from

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"

granularity

enum<string>

Bucket size used for an analytics chart window.

Available options:

hour,

day,

week,

month

Example:

"day"

metric

enum<string>

default:conversations

Measure aggregated into analytics chart points.

Available options:

conversations,

messages,

duration,

success_rate

Example:

"conversations"

timezone

string

default:UTC

Allowed value: "UTC"

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"

Response

Only the requested analytics sections, all resolved over the same returned window.

window

object

required

Show child attributes

agentPerformance

object[]

Maximum array length: 500

Show child attributes

chart

object

Show child attributes

statusBreakdown

object[]

Maximum array length: 50

Show child attributes

summary

object

Show child attributes

⌘I

Query analytics

curl --request POST \
  --url https://api.getarbol.com/v1/analytics/query \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sections": [
    "summary",
    "chart"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({sections: ['summary', 'chart']})
};

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

import requests

url = "https://api.getarbol.com/v1/analytics/query"

payload = { "sections": ["summary", "chart"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "window": {
    "from": "2026-08-29T14:30:00Z",
    "granularity": "day",
    "timezone": "UTC",
    "to": "2026-08-29T14:30:00Z"
  },
  "agentPerformance": [
    {
      "agentId": "agt_018f47a2-4f4d-7d61-9e2c-1d7b8e9a0c31",
      "averageDurationSeconds": 1,
      "conversations": 4503599627370495,
      "lastActiveAt": "2026-08-29T14:30:00Z",
      "name": "<string>",
      "successRate": 0.5
    }
  ],
  "chart": {
    "metric": "conversations",
    "points": [
      {
        "date": "<string>",
        "value": 123
      }
    ]
  },
  "statusBreakdown": [
    {
      "count": 4503599627370495,
      "key": "<string>"
    }
  ],
  "summary": {
    "averageDurationSeconds": 1,
    "contacts": 4503599627370495,
    "conversations": 4503599627370495,
    "messages": 4503599627370495,
    "successRate": 0.5
  }
}

{
  "defined": true,
  "inferable": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "<string>",
  "data": {
    "issues": [
      {
        "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"
    ]
  }
}

{
  "code": "PAYLOAD_TOO_LARGE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

{
  "code": "UNSUPPORTED_MEDIA_TYPE",
  "defined": false,
  "inferable": false,
  "message": "<string>",
  "data": "<unknown>"
}

Overview

Endpoints

Query analytics

Authorizations

Body

Response