Analytics | Developer API | Conversation Engine

Overview

The Analytics endpoints return aggregated metrics for a given chatbot. All endpoints support optional start_date and end_date query parameters to filter by time range (ISO 8601 dates).

Timezone

All timestamps in analytics responses are UTC. Pass date parameters as YYYY-MM-DD UTC dates.

Get Overview

Returns high-level aggregated statistics for a chatbot.

http

GET /api/dev/v1/chatbots/{chatbot_id}/analytics/overview
Authorization: Bearer <api-key>GET /api/dev/v1/chatbots/{chatbot_id}/analytics/overview
Authorization: Bearer <api-key>

Query Parameters

Parameters

start_datestringoptional

Start of the date range (inclusive). Format: YYYY-MM-DD. Defaults to 30 days ago.

end_datestringoptional

End of the date range (inclusive). Format: YYYY-MM-DD. Defaults to today.

bash

curl -X GET "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/overview?start_date=2026-02-01&end_date=2026-02-26" \
  -H "Authorization: Bearer <your-api-key>"curl -X GET "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/overview?start_date=2026-02-01&end_date=2026-02-26" \
  -H "Authorization: Bearer <your-api-key>"

python

import requests

params = {"start_date": "2026-02-01", "end_date": "2026-02-26"}

response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/overview",
    headers={"Authorization": "Bearer <your-api-key>"},
    params=params,
)
print(response.json())import requests

params = {"start_date": "2026-02-01", "end_date": "2026-02-26"}

response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/overview",
    headers={"Authorization": "Bearer <your-api-key>"},
    params=params,
)
print(response.json())

javascript

const params = new URLSearchParams({ start_date: "2026-02-01", end_date: "2026-02-26" });
const response = await fetch(
  `http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/overview?${params}`,
  { headers: { "Authorization": "Bearer <your-api-key>" } },
);
const data = await response.json();const params = new URLSearchParams({ start_date: "2026-02-01", end_date: "2026-02-26" });
const response = await fetch(
  `http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/overview?${params}`,
  { headers: { "Authorization": "Bearer <your-api-key>" } },
);
const data = await response.json();

Response - 200 OK

json

{
  "chatbot_id": "01JMXYZ...",
  "period": {
    "start_date": "2026-02-01",
    "end_date": "2026-02-26"
  },
  "total_conversations": 1482,
  "total_messages": 10234,
  "unique_users": 876,
  "avg_messages_per_conversation": 6.9,
  "completion_rate": 0.74
}{
  "chatbot_id": "01JMXYZ...",
  "period": {
    "start_date": "2026-02-01",
    "end_date": "2026-02-26"
  },
  "total_conversations": 1482,
  "total_messages": 10234,
  "unique_users": 876,
  "avg_messages_per_conversation": 6.9,
  "completion_rate": 0.74
}

Response Fields

Overview fields

total_conversationsinteger

Number of conversations started in the period.

total_messagesinteger

Total messages sent and received.

unique_usersinteger

Number of distinct users who interacted.

avg_messages_per_conversationnumber

Average message depth per conversation.

completion_ratenumber

Fraction of conversations that reached a terminal state (0–1).

Conversations Series

Returns a daily time series of conversation counts. Useful for charting trends.

http

GET /api/dev/v1/chatbots/{chatbot_id}/analytics/conversations
Authorization: Bearer <api-key>GET /api/dev/v1/chatbots/{chatbot_id}/analytics/conversations
Authorization: Bearer <api-key>

bash

curl -X GET "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/conversations?start_date=2026-02-01&end_date=2026-02-26" \
  -H "Authorization: Bearer <your-api-key>"curl -X GET "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/conversations?start_date=2026-02-01&end_date=2026-02-26" \
  -H "Authorization: Bearer <your-api-key>"

python

import requests

params = {"start_date": "2026-02-01", "end_date": "2026-02-26"}
response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/conversations",
    headers={"Authorization": "Bearer <your-api-key>"},
    params=params,
)
print(response.json())import requests

params = {"start_date": "2026-02-01", "end_date": "2026-02-26"}
response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/conversations",
    headers={"Authorization": "Bearer <your-api-key>"},
    params=params,
)
print(response.json())

javascript

const params = new URLSearchParams({ start_date: "2026-02-01", end_date: "2026-02-26" });
const response = await fetch(
  `http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/conversations?${params}`,
  { headers: { "Authorization": "Bearer <your-api-key>" } },
);
const data = await response.json();const params = new URLSearchParams({ start_date: "2026-02-01", end_date: "2026-02-26" });
const response = await fetch(
  `http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/conversations?${params}`,
  { headers: { "Authorization": "Bearer <your-api-key>" } },
);
const data = await response.json();

Response - 200 OK

json

{
  "series": [
    { "date": "2026-02-01", "count": 45 },
    { "date": "2026-02-02", "count": 62 },
    { "date": "2026-02-03", "count": 38 }
  ]
}{
  "series": [
    { "date": "2026-02-01", "count": 45 },
    { "date": "2026-02-02", "count": 62 },
    { "date": "2026-02-03", "count": 38 }
  ]
}

Messages Series

Returns a daily time series of message counts (inbound + outbound combined).

http

GET /api/dev/v1/chatbots/{chatbot_id}/analytics/messages
Authorization: Bearer <api-key>GET /api/dev/v1/chatbots/{chatbot_id}/analytics/messages
Authorization: Bearer <api-key>

bash

curl -X GET "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/messages?start_date=2026-02-01&end_date=2026-02-26" \
  -H "Authorization: Bearer <your-api-key>"curl -X GET "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/messages?start_date=2026-02-01&end_date=2026-02-26" \
  -H "Authorization: Bearer <your-api-key>"

python

import requests

params = {"start_date": "2026-02-01", "end_date": "2026-02-26"}
response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/messages",
    headers={"Authorization": "Bearer <your-api-key>"},
    params=params,
)
print(response.json())import requests

params = {"start_date": "2026-02-01", "end_date": "2026-02-26"}
response = requests.get(
    "http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/messages",
    headers={"Authorization": "Bearer <your-api-key>"},
    params=params,
)
print(response.json())

javascript

const params = new URLSearchParams({ start_date: "2026-02-01", end_date: "2026-02-26" });
const response = await fetch(
  `http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/messages?${params}`,
  { headers: { "Authorization": "Bearer <your-api-key>" } },
);
const data = await response.json();const params = new URLSearchParams({ start_date: "2026-02-01", end_date: "2026-02-26" });
const response = await fetch(
  `http://localhost:3000/api/dev/v1/chatbots/<chatbot-id>/analytics/messages?${params}`,
  { headers: { "Authorization": "Bearer <your-api-key>" } },
);
const data = await response.json();

Response - 200 OK

json

{
  "series": [
    { "date": "2026-02-01", "count": 310 },
    { "date": "2026-02-02", "count": 428 },
    { "date": "2026-02-03", "count": 265 }
  ]
}{
  "series": [
    { "date": "2026-02-01", "count": 310 },
    { "date": "2026-02-02", "count": 428 },
    { "date": "2026-02-03", "count": 265 }
  ]
}

Build dashboards

Combine the overview endpoint for KPI cards with the series endpoints for trend charts. Both use the same date range parameters for consistent data.