Analytics
Every call needs Authorization: Bearer <key>. 5 calls:
- Per-line and per-pool sends, delivery and replies:
GET /v1/analytics/lines - Messages by channel, status and failure code:
GET /v1/analytics/messages - Message volume, delivery, replies and opt-outs:
GET /v1/analytics/overview - Messages, conversations and response times per member:
GET /v1/analytics/team - Runs, completions, failures, handoffs and reply rate per workflow:
GET /v1/analytics/workflows
Per-line and per-pool sends, delivery and replies
GET /v1/analytics/lines
Sandbox lines are left out. Agents, who see only their own conversations, are refused, and so are test-mode API keys.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
from | string (date-time) | No | Defaults to the start of the organisation's day, 29 days before to. |
to | string (date-time) | No | Defaults to now. |
interval | enum | No | One of: hour, day, week. Default "day". |
line_id | string | No | Line id (ln_...). |
team_id | string (uuid) | No | |
pool_id | string | No | Pool id (pool_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
lines | object[] | |
lines[].delivered | integer | From 0 to 9007199254740991. |
lines[].delivery_rate | number | Fraction from 0 to 1. From 0 to 1. |
lines[].display_name | string or null | |
lines[].failed | integer | From 0 to 9007199254740991. |
lines[].health_score | integer | From 0 to 100. |
lines[].line_id | string | Line id (ln_...). |
lines[].new_contacts | integer | From 0 to 9007199254740991. |
lines[].phone | string | |
lines[].pool_id | string or null | Pool id (pool_...). |
lines[].reply_rate | number | Fraction from 0 to 1. From 0 to 1. |
lines[].sends | integer | From 0 to 9007199254740991. |
lines[].state | enum | One of: provisioning, ready, warming, active, throttled, paused, quarantined, retired. |
pools | object[] | |
pools[].delivered | integer | From 0 to 9007199254740991. |
pools[].delivery_rate | number | Fraction from 0 to 1. From 0 to 1. |
pools[].failed | integer | From 0 to 9007199254740991. |
pools[].line_count | integer | From 0 to 9007199254740991. |
pools[].name | string | |
pools[].new_contacts | integer | From 0 to 9007199254740991. |
pools[].pool_id | string | Pool id (pool_...). |
pools[].reply_rate | number | Fraction from 0 to 1. From 0 to 1. |
pools[].sends | integer | From 0 to 9007199254740991. |
range | object | |
range.from | string (date-time) | ISO 8601 timestamp. |
range.interval | enum | One of: hour, day, week. |
range.timezone | string | IANA time zone. Up to 64 characters. |
range.to | string (date-time) | ISO 8601 timestamp. |
states | object |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Messages by channel, status and failure code
GET /v1/analytics/messages
Agents see only conversations assigned to them. Sandbox traffic is left out, and test-mode API keys are refused.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
from | string (date-time) | No | Defaults to the start of the organisation's day, 29 days before to. |
to | string (date-time) | No | Defaults to now. |
interval | enum | No | One of: hour, day, week. Default "day". |
line_id | string | No | Line id (ln_...). |
team_id | string (uuid) | No | |
pool_id | string | No | Pool id (pool_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
by_channel | object[] | |
by_channel[].channel | enum | One of: imessage, sms. |
by_channel[].delivered | integer | From 0 to 9007199254740991. |
by_channel[].sent | integer | From 0 to 9007199254740991. |
by_status | object[] | |
by_status[].count | integer | From 0 to 9007199254740991. |
by_status[].status | string | |
failures_by_code | object[] | |
failures_by_code[].count | integer | From 0 to 9007199254740991. |
failures_by_code[].error_code | string | |
range | object | |
range.from | string (date-time) | ISO 8601 timestamp. |
range.interval | enum | One of: hour, day, week. |
range.timezone | string | IANA time zone. Up to 64 characters. |
range.to | string (date-time) | ISO 8601 timestamp. |
series | object[] | |
series[].failed | integer | From 0 to 9007199254740991. |
series[].imessage | integer | From 0 to 9007199254740991. |
series[].inbound | integer | From 0 to 9007199254740991. |
series[].sms | integer | From 0 to 9007199254740991. |
series[].t | string (date-time) | Bucket start. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Message volume, delivery, replies and opt-outs
GET /v1/analytics/overview
Totals and a series for the range. Agents see only conversations assigned to them. Sandbox traffic is left out, and test-mode API keys are refused.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
from | string (date-time) | No | Defaults to the start of the organisation's day, 29 days before to. |
to | string (date-time) | No | Defaults to now. |
interval | enum | No | One of: hour, day, week. Default "day". |
line_id | string | No | Line id (ln_...). |
team_id | string (uuid) | No | |
pool_id | string | No | Pool id (pool_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
range | object | |
range.from | string (date-time) | ISO 8601 timestamp. |
range.interval | enum | One of: hour, day, week. |
range.timezone | string | IANA time zone. Up to 64 characters. |
range.to | string (date-time) | ISO 8601 timestamp. |
series | object[] | |
series[].delivered | integer | From 0 to 9007199254740991. |
series[].failed | integer | From 0 to 9007199254740991. |
series[].opt_outs | integer | From 0 to 9007199254740991. |
series[].received | integer | From 0 to 9007199254740991. |
series[].reply_rate | number or null | Null when nobody was messaged in the bucket. From 0 to 1. |
series[].sent | integer | From 0 to 9007199254740991. |
series[].t | string (date-time) | Bucket start. |
totals | object | |
totals.delivered | integer | From 0 to 9007199254740991. |
totals.delivery_rate | number | Fraction from 0 to 1. From 0 to 1. |
totals.failed | integer | From 0 to 9007199254740991. |
totals.median_first_response_seconds | number or null | |
totals.messaged_contacts | integer | From 0 to 9007199254740991. |
totals.new_contacts | integer | From 0 to 9007199254740991. |
totals.open_conversations | integer | From 0 to 9007199254740991. |
totals.opt_outs | integer | From 0 to 9007199254740991. |
totals.received | integer | From 0 to 9007199254740991. |
totals.replied_contacts | integer | From 0 to 9007199254740991. |
totals.reply_rate | number | Fraction from 0 to 1. From 0 to 1. |
totals.sent | integer | From 0 to 9007199254740991. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Messages, conversations and response times per member
GET /v1/analytics/team
Active members of the workspace, with their names. Signed-in users only: API keys never reach team details. Agents see only their own row.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
from | string (date-time) | No | Defaults to the start of the organisation's day, 29 days before to. |
to | string (date-time) | No | Defaults to now. |
interval | enum | No | One of: hour, day, week. Default "day". |
line_id | string | No | Line id (ln_...). |
team_id | string (uuid) | No | |
pool_id | string | No | Pool id (pool_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
members | object[] | |
members[].closed | integer | From 0 to 9007199254740991. |
members[].conversations_handled | integer | From 0 to 9007199254740991. |
members[].full_name | string or null | |
members[].median_first_response_seconds | number or null | |
members[].messages_sent | integer | From 0 to 9007199254740991. |
members[].role | enum | One of: owner, admin, billing, manager, agent, developer, analyst. |
members[].user_id | string (uuid) | |
range | object | |
range.from | string (date-time) | ISO 8601 timestamp. |
range.interval | enum | One of: hour, day, week. |
range.timezone | string | IANA time zone. Up to 64 characters. |
range.to | string (date-time) | ISO 8601 timestamp. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Runs, completions, failures, handoffs and reply rate per workflow
GET /v1/analytics/workflows
Runs started in the range, by workflow, busiest first. A handoff is a run that assigned the conversation to a person or team. The reply rate is the share of contacts the workflow messaged in the range who wrote back after its first message to them. Test-mode API keys are refused.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
from | string (date-time) | No | Defaults to the start of the organisation's day, 29 days before to. |
to | string (date-time) | No | Defaults to now. |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
range | object | |
range.from | string (date-time) | ISO 8601 timestamp. |
range.interval | enum | One of: hour, day, week. |
range.timezone | string | IANA time zone. Up to 64 characters. |
range.to | string (date-time) | ISO 8601 timestamp. |
workflows | object[] | |
workflows[].completed | integer | From 0 to 9007199254740991. |
workflows[].failed | integer | From 0 to 9007199254740991. |
workflows[].handoffs | integer | From 0 to 9007199254740991. |
workflows[].messaged_contacts | integer | From 0 to 9007199254740991. |
workflows[].name | string | |
workflows[].replied_contacts | integer | From 0 to 9007199254740991. |
workflows[].reply_rate | number or null | Null when the workflow messaged nobody in the range. From 0 to 1. |
workflows[].runs | integer | From 0 to 9007199254740991. |
workflows[].workflow_id | string (uuid) |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.