Documentation Index Fetch the complete documentation index at: https://docs.kaie.ai/llms.txt
Use this file to discover all available pages before exploring further.
Analytics API The Analytics API provides programmatic access to your workflow performance data, customer engagement metrics, and business intelligence. Use this API to build custom dashboards, generate reports, and integrate analytics into your own applications.
Overview The Analytics API allows you to:
Retrieve workflow performance metrics
Access customer engagement data
Get real-time analytics
Export historical data
Create custom reports
Authentication All Analytics API requests require authentication. Include your API key in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.kaie.ai/v1/analytics/workflows
Workflow Analytics Get Workflow Metrics Retrieve comprehensive metrics for a specific workflow.
Request GET /v1/analytics/workflows/{workflow_id}
Parameters Parameter Type Description start_datestring Start date for metrics (ISO 8601) end_datestring End date for metrics (ISO 8601) granularitystring Data granularity (hour, day, week, month) metricsarray Specific metrics to include group_byarray Group data by fields
Response { "data" : { "workflow_id" : "workflow-123" , "period" : { "start_date" : "2024-01-01T00:00:00Z" , "end_date" : "2024-01-31T23:59:59Z" }, "metrics" : { "total_executions" : 1250 , "successful_executions" : 1187 , "failed_executions" : 63 , "success_rate" : 0.95 , "average_duration_ms" : 12000 , "total_messages_sent" : 2500 , "total_messages_received" : 1250 , "unique_customers" : 450 , "customer_satisfaction" : 4.2 , "channel_breakdown" : { "whatsapp" : 800 , "instagram" : 300 , "voice" : 150 } }, "trends" : { "execution_trend" : "increasing" , "success_rate_trend" : "stable" , "duration_trend" : "decreasing" }, "daily_metrics" : [ { "date" : "2024-01-01" , "executions" : 45 , "success_rate" : 0.96 , "average_duration_ms" : 11500 , "messages_sent" : 90 , "messages_received" : 45 , "unique_customers" : 25 } ] } }
Get detailed performance metrics for a workflow.
Request GET /v1/analytics/workflows/{workflow_id}/performance
Parameters Parameter Type Description start_datestring Start date for metrics (ISO 8601) end_datestring End date for metrics (ISO 8601) include_nodesboolean Include node-level metrics include_channelsboolean Include channel breakdown
Response { "data" : { "workflow_id" : "workflow-123" , "period" : { "start_date" : "2024-01-01T00:00:00Z" , "end_date" : "2024-01-31T23:59:59Z" }, "performance" : { "execution_time" : { "average_ms" : 12000 , "median_ms" : 11000 , "p95_ms" : 25000 , "p99_ms" : 45000 }, "throughput" : { "executions_per_hour" : 15.6 , "peak_executions_per_hour" : 45 , "peak_hour" : "14:00" }, "error_rate" : { "overall" : 0.05 , "by_error_type" : { "timeout" : 0.03 , "api_error" : 0.01 , "validation_error" : 0.01 } }, "node_performance" : [ { "node_id" : "welcome" , "type" : "message" , "execution_count" : 1250 , "success_rate" : 0.99 , "average_duration_ms" : 500 , "error_count" : 12 } ], "channel_performance" : { "whatsapp" : { "executions" : 800 , "success_rate" : 0.96 , "average_duration_ms" : 10000 }, "instagram" : { "executions" : 300 , "success_rate" : 0.94 , "average_duration_ms" : 15000 } } } } }
Customer Analytics Get Customer Engagement Retrieve customer engagement metrics.
Request GET /v1/analytics/customers/engagement
Parameters Parameter Type Description start_datestring Start date for metrics (ISO 8601) end_datestring End date for metrics (ISO 8601) customer_segmentstring Filter by customer segment channelstring Filter by communication channel
Response { "data" : { "period" : { "start_date" : "2024-01-01T00:00:00Z" , "end_date" : "2024-01-31T23:59:59Z" }, "engagement" : { "total_customers" : 450 , "active_customers" : 380 , "new_customers" : 50 , "returning_customers" : 330 , "average_session_duration" : 300 , "average_messages_per_session" : 5.2 , "customer_satisfaction" : 4.2 , "net_promoter_score" : 8.5 , "engagement_by_channel" : { "whatsapp" : { "customers" : 300 , "average_session_duration" : 250 , "satisfaction" : 4.3 }, "instagram" : { "customers" : 150 , "average_session_duration" : 400 , "satisfaction" : 4.1 } } }, "trends" : { "customer_growth" : "increasing" , "engagement_trend" : "stable" , "satisfaction_trend" : "increasing" } } }
Get Customer Journey Analyze customer journey patterns.
Request GET /v1/analytics/customers/journey
Parameters Parameter Type Description start_datestring Start date for analysis (ISO 8601) end_datestring End date for analysis (ISO 8601) journey_typestring Type of journey to analyze include_dropoffsboolean Include drop-off analysis
Response { "data" : { "period" : { "start_date" : "2024-01-01T00:00:00Z" , "end_date" : "2024-01-31T23:59:59Z" }, "journey" : { "total_journeys" : 1250 , "completed_journeys" : 1000 , "completion_rate" : 0.8 , "average_journey_duration" : 1800 , "journey_steps" : [ { "step" : 1 , "name" : "Welcome" , "customers" : 1250 , "completion_rate" : 1.0 , "average_duration_ms" : 500 }, { "step" : 2 , "name" : "Information Collection" , "customers" : 1200 , "completion_rate" : 0.96 , "average_duration_ms" : 15000 }, { "step" : 3 , "name" : "Resolution" , "customers" : 1000 , "completion_rate" : 0.83 , "average_duration_ms" : 30000 } ], "drop_off_points" : [ { "step" : 2 , "name" : "Information Collection" , "drop_off_count" : 50 , "drop_off_rate" : 0.04 , "common_reasons" : [ "timeout" , "user_abandoned" ] } ] } } }
Real-time Analytics Get Real-time Metrics Retrieve real-time analytics data.
Request GET /v1/analytics/realtime
Parameters Parameter Type Description workflow_idstring Filter by specific workflow channelstring Filter by communication channel include_systemboolean Include system performance metrics
Response { "data" : { "timestamp" : "2024-01-25T14:30:00Z" , "current_metrics" : { "active_workflows" : 15 , "active_executions" : 25 , "messages_in_last_hour" : 150 , "average_response_time_ms" : 8000 , "system_health" : "healthy" }, "workflow_metrics" : [ { "workflow_id" : "workflow-123" , "name" : "Customer Support Bot" , "active_executions" : 5 , "messages_in_last_hour" : 45 , "average_response_time_ms" : 7500 } ], "channel_metrics" : { "whatsapp" : { "active_conversations" : 20 , "messages_in_last_hour" : 100 }, "instagram" : { "active_conversations" : 5 , "messages_in_last_hour" : 50 } }, "system_metrics" : { "cpu_usage" : 45.2 , "memory_usage" : 67.8 , "api_response_time_ms" : 150 } } }
Custom Reports Create Custom Report Create a custom analytics report.
Request POST /v1/analytics/reports
Request Body { "name" : "Monthly Performance Report" , "description" : "Monthly performance report for all workflows" , "metrics" : [ "total_executions" , "success_rate" , "average_duration_ms" , "customer_satisfaction" ], "filters" : { "start_date" : "2024-01-01T00:00:00Z" , "end_date" : "2024-01-31T23:59:59Z" , "workflow_ids" : [ "workflow-123" , "workflow-456" ] }, "group_by" : [ "workflow_id" , "channel" ], "granularity" : "day" }
Response { "data" : { "report_id" : "report-789" , "name" : "Monthly Performance Report" , "status" : "generating" , "created_at" : "2024-01-25T14:30:00Z" , "estimated_completion" : "2024-01-25T14:35:00Z" } }
Get Report Status Check the status of a custom report.
Request GET /v1/analytics/reports/{report_id}
Response { "data" : { "report_id" : "report-789" , "name" : "Monthly Performance Report" , "status" : "completed" , "created_at" : "2024-01-25T14:30:00Z" , "completed_at" : "2024-01-25T14:32:00Z" , "download_url" : "https://api.kaie.ai/v1/analytics/reports/report-789/download" , "expires_at" : "2024-02-01T14:30:00Z" } }
Download Report Download a completed report.
Request GET /v1/analytics/reports/{report_id}/download
Response The response will be the report file (CSV, JSON, or PDF depending on the format requested).
Data Export Export Analytics Data Export analytics data in various formats.
Request POST /v1/analytics/export
Request Body { "data_type" : "workflow_metrics" , "format" : "csv" , "start_date" : "2024-01-01T00:00:00Z" , "end_date" : "2024-01-31T23:59:59Z" , "filters" : { "workflow_ids" : [ "workflow-123" , "workflow-456" ], "channels" : [ "whatsapp" , "instagram" ] }, "include_metadata" : true }
Response { "data" : { "export_id" : "export-123" , "status" : "processing" , "created_at" : "2024-01-25T14:30:00Z" , "estimated_completion" : "2024-01-25T14:35:00Z" , "download_url" : "https://api.kaie.ai/v1/analytics/export/export-123/download" } }
Error Handling Common Error Codes Status Code Error Code Description 400 INVALID_DATE_RANGEDate range is invalid 400 INVALID_METRICSRequested metrics are invalid 404 WORKFLOW_NOT_FOUNDWorkflow does not exist 422 INVALID_GRANULARITYGranularity parameter is invalid 429 RATE_LIMIT_EXCEEDEDRate limit exceeded 500 REPORT_GENERATION_FAILEDReport generation failed
{ "error" : { "code" : "INVALID_DATE_RANGE" , "message" : "Date range is invalid" , "details" : "End date must be after start date" , "field" : "end_date" } }
Rate Limiting Analytics API endpoints are subject to rate limiting:
Real-time metrics : 1000 requests per hourHistorical metrics : 100 requests per hourCustom reports : 50 requests per hourData export : 20 requests per hour
Best Practices Efficient Data Retrieval
Use appropriate date ranges for your needs
Avoid requesting data for very long periods
Use granularity to reduce data volume
Only request metrics you need
Use filters to reduce data volume
Cache frequently accessed data
Cache analytics data when possible
Use appropriate cache TTL values
Implement cache invalidation strategies
Next Steps Explore more API endpoints:
Workflows API Manage workflows programmatically
Triggers API Manage workflow triggers
Webhooks API Set up webhook integrations
Authentication Learn about API authentication
