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_date`	string	Start date for metrics (ISO 8601)
`end_date`	string	End date for metrics (ISO 8601)
`granularity`	string	Data granularity (`hour`, `day`, `week`, `month`)
`metrics`	array	Specific metrics to include
`group_by`	array	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 Workflow Performance

Get detailed performance metrics for a workflow.

Request

GET /v1/analytics/workflows/{workflow_id}/performance

Parameters

Parameter	Type	Description
`start_date`	string	Start date for metrics (ISO 8601)
`end_date`	string	End date for metrics (ISO 8601)
`include_nodes`	boolean	Include node-level metrics
`include_channels`	boolean	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_date`	string	Start date for metrics (ISO 8601)
`end_date`	string	End date for metrics (ISO 8601)
`customer_segment`	string	Filter by customer segment
`channel`	string	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_date`	string	Start date for analysis (ISO 8601)
`end_date`	string	End date for analysis (ISO 8601)
`journey_type`	string	Type of journey to analyze
`include_dropoffs`	boolean	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_id`	string	Filter by specific workflow
`channel`	string	Filter by communication channel
`include_system`	boolean	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_RANGE`	Date range is invalid
400	`INVALID_METRICS`	Requested metrics are invalid
404	`WORKFLOW_NOT_FOUND`	Workflow does not exist
422	`INVALID_GRANULARITY`	Granularity parameter is invalid
429	`RATE_LIMIT_EXCEEDED`	Rate limit exceeded
500	`REPORT_GENERATION_FAILED`	Report generation failed

Error Response Format

{
  "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 hour
Historical metrics: 100 requests per hour
Custom reports: 50 requests per hour
Data export: 20 requests per hour

Best Practices

Efficient Data Retrieval

Date Range Selection

Use appropriate date ranges for your needs
Avoid requesting data for very long periods
Use granularity to reduce data volume

Metric Selection

Only request metrics you need
Use filters to reduce data volume
Cache frequently accessed data

Performance Optimization

Caching

Cache analytics data when possible
Use appropriate cache TTL values
Implement cache invalidation strategies

Pagination

Use pagination for large datasets
Set appropriate page sizes
Implement efficient pagination logic

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

​Analytics API

​Overview

​Authentication

​Workflow Analytics

​Get Workflow Metrics

​Request

​Parameters

​Response

​Get Workflow Performance

​Request

​Parameters

​Response

​Customer Analytics

​Get Customer Engagement

​Request

​Parameters

​Response

​Get Customer Journey

​Request

​Parameters

​Response

​Real-time Analytics

​Get Real-time Metrics

​Request

​Parameters

​Response

​Custom Reports

​Create Custom Report

​Request

​Request Body

​Response

​Get Report Status

​Request

​Response

​Download Report

​Request

​Response

​Data Export

​Export Analytics Data

​Request

​Request Body

​Response

​Error Handling

​Common Error Codes

​Error Response Format

​Rate Limiting

​Best Practices

​Efficient Data Retrieval

​Performance Optimization

​Next Steps

Workflows API

Triggers API

Webhooks API

Authentication

Analytics API

Overview

Authentication

Workflow Analytics

Get Workflow Metrics

Request

Parameters

Response

Get Workflow Performance

Request

Parameters

Response

Customer Analytics

Get Customer Engagement

Request

Parameters

Response

Get Customer Journey

Request

Parameters

Response

Real-time Analytics

Get Real-time Metrics

Request

Parameters

Response

Custom Reports

Create Custom Report

Request

Request Body

Response

Get Report Status

Request

Response

Download Report

Request

Response

Data Export

Export Analytics Data

Request

Request Body

Response

Error Handling

Common Error Codes

Error Response Format

Rate Limiting

Best Practices

Efficient Data Retrieval

Performance Optimization

Next Steps