Analytics
Operations tagged Analytics in the public API.
About Analytics
Analytics is the account's chat activity over the last 7, 30 or 90 days: daily series, period totals with the period before for comparison, and breakdowns by answer status, rating and chatbot — the figures of the dashboard home page, computed live on each call.
Days are UTC. The window ends today (UTC), still in progress, and starts range − 1 days earlier; from and to name its first and last day. previous_totals covers the same number of days just before from. There is no custom range or timezone: for other windows, page GET /conversations with created[gte] / created[lte] and count yourself.
What is counted. A message is one turn — a visitor's message and its reply — from any surface: the API, the widget, the hosted agent page, the dashboard Test Chat or a messaging channel. A conversation is one with at least one message, counted on the day it started. Rates are percentages from 0 to 100 with one decimal, and 0 when there is nothing to divide by. Deleted conversations no longer count.
IDs you will meet.
id— the account id, the same value asidonGET /me.chatbot_id— pass it to count one chatbot;breakdowns.top_chatbots[].idis a chatbot id.
IDs on this page
- Chatbot id
<CHATBOT_ID> - Integer.
Get it from
- GET /v1/chatbots returns it as
data[].id - POST /v1/chatbots returns it as
id - GET /v1/chatbots/by_handle/{handle} returns it as
id - Webhook chatbot.created carries it as
data.object.id - In the dashboard, it is the number in a chatbot's address:
/dashboard/chatbots/{id}.
- GET /v1/chatbots returns it as
Retrieve dashboard analytics
series, the window's totals and the previous_totals of the window before it, and breakdowns by reply status, rating and busiest chatbot. It covers every chatbot the API key reaches, or one with chatbot_id.
Computed live on each call, from the same definitions as the dashboard home page — which counts in the viewer's timezone, so the two can differ around midnight.- Required scope
- analytics:read
- Idempotency
- Read-only
- Rate limits
Integer.chatbot_id(query)Chatbot idPlaceholder in the samples:
<CHATBOT_ID>Get it from
- GET /v1/chatbots returns it as
data[].id - POST /v1/chatbots returns it as
id - GET /v1/chatbots/by_handle/{handle} returns it as
id - Webhook chatbot.created carries it as
data.object.id - In the dashboard, it is the number in a chatbot's address:
/dashboard/chatbots/{id}.
- GET /v1/chatbots returns it as
Query parameters
rangestringOptionalThe window: the last7d,30dor90ddays, today (UTC) included. Defaults to7d.Possible values
7d30d90dDefault:
"7d"chatbot_idintegerOptionalCount one chatbot only. A chatbot the API key cannot reach is 404NOT_FOUND.Minimum:
1
Responses
- 200Success.
objectstringRequiredAlways
analytics_dashboardidintegerRequiredThe account id, the same value asidonGET /me.rangestringRequiredThe window: the last 7, 30 or 90 days.7dwhen the request named none.Possible values
30d90d7dfromstringRequiredFirst day of the window (YYYY-MM-DD, UTC).Format:
datetostringRequiredLast day of the window: today in UTC, still in progress (YYYY-MM-DD).Format:
dateseriesarray of objectRequiredOne row per day of the window, oldest first; a day without activity is a row of zeros.totalsobjectRequiredTotals over the window. The series adds up to them.previous_totalsobjectRequiredThe same totals over the window of equal length that ends the day beforefrom, for a trend comparison.breakdownsobjectRequiredThe window's messages broken down.total_chatbotsintegerRequiredHow many chatbots the figures cover: every chatbot the API key reaches, or1withchatbot_id.
- 400A tenant selector header named a tenant other than the API key's own (
ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digitX-Account-Idother than the key owner's id or, whileworkspaces.context_enabledis on, anX-Workspace-Idother than the key's workspace (ws_prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numericX-Account-Id, is ignored; a key cannot switch tenants, so send neither.Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
- 401Missing or invalid API key.
Error codesUNAUTHENTICATED
- 403The API key is missing a required scope.
Error codesACCOUNT_SUSPENDEDINSUFFICIENT_SCOPE
- 404The resource does not exist on this account.
Error codesNOT_FOUND
- 422Validation failed. See
error.details.Error codesVALIDATION_FAILED
- 429Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
- 500Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR
Request
curl -X GET 'https://api.agentency.com/v1/analytics/dashboard' \
-H "Authorization: Bearer <YOUR_KEY>" \
-H "Content-Type: application/json"Response
Example 200 response
{
"object": "analytics_dashboard",
"id": 1,
"range": "7d",
"from": "2025-12-26",
"to": "2026-01-01",
"series": [
{
"date": "2025-12-26",
"messages": 0,
"conversations": 0,
"answered": 0,
"partial": 0,
"no_answer": 0,
"avg_response_ms": 0
},
{
"date": "2025-12-27",
"messages": 0,
"conversations": 0,
"answered": 0,
"partial": 0,
"no_answer": 0,
"avg_response_ms": 0
},
{
"date": "2025-12-28",
"messages": 0,
"conversations": 0,
"answered": 0,
"partial": 0,
"no_answer": 0,
"avg_response_ms": 0
},
{
"date": "2025-12-29",
"messages": 0,
"conversations": 0,
"answered": 0,
"partial": 0,
"no_answer": 0,
"avg_response_ms": 0
},
{
"date": "2025-12-30",
"messages": 0,
"conversations": 0,
"answered": 0,
"partial": 0,
"no_answer": 0,
"avg_response_ms": 0
},
{
"date": "2025-12-31",
"messages": 0,
"conversations": 0,
"answered": 0,
"partial": 0,
"no_answer": 0,
"avg_response_ms": 0
},
{
"date": "2026-01-01",
"messages": 1,
"conversations": 1,
"answered": 1,
"partial": 0,
"no_answer": 0,
"avg_response_ms": 1808
}
],
"totals": {
"messages": 1,
"conversations": 1,
"success_rate": 100,
"avg_response_ms": 1808.4,
"feedback_positive": 0,
"feedback_negative": 0,
"resolution_rate": 0,
"handoff_rate": 0
},
"previous_totals": {
"messages": 0,
"conversations": 0,
"success_rate": 0,
"avg_response_ms": 0,
"feedback_positive": 0,
"feedback_negative": 0,
"resolution_rate": 0,
"handoff_rate": 0
},
"breakdowns": {
"status": {
"answered": 1,
"partial_answer": 0,
"no_answer": 0
},
"feedback": {
"positive": 0,
"negative": 0
},
"top_chatbots": [
{
"id": 1,
"name": "Support Assistant",
"slug": "support-assistant",
"avatar": null,
"color": "bg-indigo-500",
"is_image_avatar": false,
"status": "active",
"training_status": "never_trained",
"messages": 1,
"success_rate": 100
}
]
},
"total_chatbots": 2
}