Agent API/Analytics
Conversation Summary
Returns aggregated conversation statistics for a given period scoped to your agent. Use the ?month= parameter to fetch a full calendar month (e.g. March 2026). Includes total conversations, messages, completion rate, channel breakdown, lead count, and escalation count. For organization-owned agents this is served from a pre-aggregated table — fast even for large volumes.
GET
https://agent.askhandle.com/api/v1/public/analytics/conversations/summaryRequires X-API-Key — Your agent API key (pk_live_...)
Request
Headers
X-API-Keystringrequired
Your agent API key (pk_live_...)
Query Parameters
monthstring
Calendar month in YYYY-MM format (e.g. "2026-03"). Preferred over start/end.
startstring
Start date ISO string (e.g. "2026-03-01"). Requires end.
endstring
End date ISO string (e.g. "2026-03-31"). Requires start.
Response
Success 200
JSON
{
"workflow": {
"id": "wf_xyz789",
"name": "Customer Support Bot"
},
"range": {
"startDate": "2026-03-01",
"endDate": "2026-03-31",
"month": "March 2026"
},
"summary": {
"totalConversations": 142,
"totalMessages": 1087,
"avgMessagesPerConversation": 7.6,
"completionRate": 68.3,
"channelBreakdown": {
"widget": 90,
"api": 35,
"portal": 17,
"web": 0,
"whatsapp": 0,
"test": 0
},
"completionBreakdown": {
"completed": 97,
"timeout": 23,
"userClose": 22,
"other": 0
},
"leadCount": 58,
"escalationCount": 4
}
}Errors
401
API key missing or invalid
Error
{
"error": "Missing API key. Include X-API-Key header."
}429
Rate limit exceeded
Error
{
"error": "Rate limit exceeded",
"retryAfter": 60
}Code examples
const res = await fetch(
'https://agent.askhandle.com/api/v1/public/analytics/conversations/summary?month=2026-03',
{ headers: { 'X-API-Key': 'pk_live_your_api_key_here' } }
);
const { summary, range } = await res.json();
console.log(`${range.month}: ${summary.totalConversations} conversations`);
console.log('Completion rate:', summary.completionRate + '%');