Analytics API
The Analytics API provides endpoints for tracking, analyzing, and reporting on bot usage and performance metrics.
Status: Roadmap
This API is on the development roadmap. The endpoints documented below represent the planned interface design.
Base URL
http://localhost:8080/api/v1/analytics
Authentication
Uses the standard botserver authentication mechanism with appropriate role-based permissions.
Endpoints
Usage Statistics
| Method |
Endpoint |
Description |
| GET |
/api/v1/analytics/usage |
Get overall usage statistics |
| GET |
/api/v1/analytics/usage/daily |
Get daily usage breakdown |
| GET |
/api/v1/analytics/usage/monthly |
Get monthly usage summary |
Conversation Metrics
| Method |
Endpoint |
Description |
| GET |
/api/v1/analytics/conversations |
Get conversation metrics |
| GET |
/api/v1/analytics/conversations/volume |
Get conversation volume over time |
| GET |
/api/v1/analytics/conversations/duration |
Get average conversation duration |
| GET |
/api/v1/analytics/conversations/resolution |
Get resolution rate metrics |
User Engagement
| Method |
Endpoint |
Description |
| GET |
/api/v1/analytics/engagement |
Get user engagement metrics |
| GET |
/api/v1/analytics/engagement/retention |
Get user retention data |
| GET |
/api/v1/analytics/engagement/satisfaction |
Get satisfaction scores |
Reports
| Method |
Endpoint |
Description |
| POST |
/api/v1/analytics/reports |
Generate a custom report |
| GET |
/api/v1/analytics/reports/{report_id} |
Get report by ID |
| GET |
/api/v1/analytics/reports |
List all reports |
Real-time Metrics
| Method |
Endpoint |
Description |
| GET |
/api/v1/analytics/realtime |
Get real-time metrics |
| GET |
/api/v1/analytics/realtime/active |
Get active sessions count |
Request Examples
Get Usage Statistics
stats = GET "/api/v1/analytics/usage"
TALK "Total conversations: " + stats.total_conversations
TALK "Active users: " + stats.active_users
Get Daily Usage
daily = GET "/api/v1/analytics/usage/daily?days=7"
FOR EACH day IN daily.data
TALK day.date + ": " + day.conversations + " conversations"
NEXT
Generate Custom Report
report_config = NEW OBJECT
report_config.type = "engagement"
report_config.start_date = "2025-01-01"
report_config.end_date = "2025-01-31"
report_config.format = "pdf"
report = POST "/api/v1/analytics/reports", report_config
TALK "Report ID: " + report.id
Get Real-time Metrics
realtime = GET "/api/v1/analytics/realtime"
TALK "Active sessions: " + realtime.active_sessions
TALK "Messages per minute: " + realtime.messages_per_minute
Response Codes
| Code |
Description |
| 200 |
Success |
| 400 |
Bad Request (invalid parameters) |
| 401 |
Unauthorized |
| 403 |
Forbidden (insufficient permissions) |
| 404 |
Not Found |
| 500 |
Internal Server Error |
Query Parameters
Time Range Filters
| Parameter |
Type |
Description |
start_date |
String |
Start date (ISO 8601 format) |
end_date |
String |
End date (ISO 8601 format) |
days |
Integer |
Number of days to include |
period |
String |
Predefined period (today, week, month, year) |
Grouping Options
| Parameter |
Type |
Description |
group_by |
String |
Group results by (hour, day, week, month) |
bot_id |
UUID |
Filter by specific bot |
user_id |
UUID |
Filter by specific user |
Required Permissions
| Endpoint Category |
Required Role |
| Usage Statistics |
analytics_viewer or admin |
| Conversation Metrics |
analytics_viewer or admin |
| User Engagement |
analytics_viewer or admin |
| Reports |
analytics_admin or admin |
| Real-time Metrics |
analytics_viewer or admin |
