The Analytics API provides endpoints for tracking, analyzing, and reporting on bot usage and performance metrics.
This API is on the development roadmap. The endpoints documented below represent the planned interface design.
http://localhost:9000/api/v1/analytics
Uses the standard botserver authentication mechanism with appropriate role-based permissions.
| 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 |
| 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 |
| 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 |
| 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 |
| Method | Endpoint | Description |
|---|
| GET | /api/v1/analytics/realtime | Get real-time metrics |
| GET | /api/v1/analytics/realtime/active | Get active sessions count |
stats = GET "/api/v1/analytics/usage"
TALK "Total conversations: " + stats.total_conversations
TALK "Active users: " + stats.active_users
daily = GET "/api/v1/analytics/usage/daily?days=7"
FOR EACH day IN daily.data
TALK day.date + ": " + day.conversations + " conversations"
NEXT
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
realtime = GET "/api/v1/analytics/realtime"
TALK "Active sessions: " + realtime.active_sessions
TALK "Messages per minute: " + realtime.messages_per_minute
| Code | Description |
|---|
| 200 | Success |
| 400 | Bad Request (invalid parameters) |
| 401 | Unauthorized |
| 403 | Forbidden (insufficient permissions) |
| 404 | Not Found |
| 500 | Internal Server Error |
| 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) |
| 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 |
| 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 |