Analytics

Analytics API

The Analytics API provides comprehensive performance monitoring, usage tracking, and insights for your AI agents. Monitor agent interactions, track performance metrics, and get AI-generated insights to optimize your deployments.

Info: All analytics endpoints require authentication using the x-api-token header.

Overview

  • Interaction Tracking: Record and retrieve agent interactions
  • Performance Metrics: Monitor agent performance over time
  • Company Analytics: Get company-wide insights and trends
  • Usage Monitoring: Track token consumption and costs

Authentication

curl -H "x-api-token: YOUR_API_TOKEN" \
  https://api.aloochat.ai/api/v1/analytics/...

Interaction Tracking

Record Agent Interaction

cURL:

curl -X POST https://api.aloochat.ai/api/v1/analytics/interactions \
  -H "x-api-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "query_text": "What are your business hours?",
    "response_text": "Our business hours are Monday-Friday, 9 AM to 6 PM EST.",
    "response_time_ms": 1250,
    "was_resolved": true
  }'

JavaScript:

const response = await fetch('https://api.aloochat.ai/api/v1/analytics/interactions', {
  method: 'POST',
  headers: {
    'x-api-token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: '123e4567-e89b-12d3-a456-426614174000',
    query_text: 'What are your business hours?',
    response_text: 'Our business hours are Monday-Friday, 9 AM to 6 PM EST.',
    response_time_ms: 1250,
    was_resolved: true
  })
});

Get Agent Interactions

Retrieve agent interactions with filtering and pagination.

cURL:

curl "https://api.aloochat.ai/api/v1/analytics/interactions?agent_id=123e4567-e89b-12d3-a456-426614174000&limit=50" \
  -H "x-api-token: YOUR_API_TOKEN"

JavaScript:

const params = new URLSearchParams({
  agent_id: '123e4567-e89b-12d3-a456-426614174000',
  limit: '50',
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-01-31T23:59:59Z'
});
 
const response = await fetch(`https://api.aloochat.ai/api/v1/analytics/interactions?${params}`, {
  headers: {
    'x-api-token': 'YOUR_API_TOKEN'
  }
});
 
const interactions = await response.json();
console.log('Interactions:', interactions);

Python:

import requests
 
params = {
    'agent_id': '123e4567-e89b-12d3-a456-426614174000',
    'limit': 50,
    'start_date': '2024-01-01T00:00:00Z',
    'end_date': '2024-01-31T23:59:59Z'
}
 
response = requests.get(
    'https://api.aloochat.ai/api/v1/analytics/interactions',
    headers={'x-api-token': 'YOUR_API_TOKEN'},
    params=params
)
 
interactions = response.json()
print('Interactions:', interactions)

Performance Metrics

Get Agent Performance

Get detailed performance metrics for a specific agent over time.

cURL:

curl "https://api.aloochat.ai/api/v1/analytics/agents/123e4567-e89b-12d3-a456-426614174000/performance?start_date=2024-01-01&end_date=2024-01-31" \
  -H "x-api-token: YOUR_API_TOKEN"

JavaScript:

const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.aloochat.ai/api/v1/analytics/agents/${agentId}/performance?start_date=2024-01-01&end_date=2024-01-31`, {
  headers: { 'x-api-token': 'YOUR_API_TOKEN' }
});

Python:

import requests
 
agent_id = '123e4567-e89b-12d3-a456-426614174000'
params = {
    'start_date': '2024-01-01',
    'end_date': '2024-01-31'
}
 
response = requests.get(
    f'https://api.aloochat.ai/api/v1/analytics/agents/{agent_id}/performance',
    headers={'x-api-token': 'YOUR_API_TOKEN'},
    params=params
)
 
performance = response.json()
print('Agent performance:', performance)

Get Daily Metrics

Get daily aggregated metrics for an agent.

cURL:

curl "https://api.aloochat.ai/api/v1/analytics/agents/123e4567-e89b-12d3-a456-426614174000/daily-metrics?start_date=2024-01-01&end_date=2024-01-31" \
  -H "x-api-token: YOUR_API_TOKEN"

JavaScript:

const agentId = '123e4567-e89b-12d3-a456-426614174000';
const params = new URLSearchParams({
  start_date: '2024-01-01',
  end_date: '2024-01-31',
  limit: '30'
});
 
const response = await fetch(`https://api.aloochat.ai/api/v1/analytics/agents/${agentId}/daily-metrics?${params}`, {
  headers: {
    'x-api-token': 'YOUR_API_TOKEN'
  }
});
 
const dailyMetrics = await response.json();
console.log('Daily metrics:', dailyMetrics);

Python:

import requests
 
agent_id = '123e4567-e89b-12d3-a456-426614174000'
params = {
    'start_date': '2024-01-01',
    'end_date': '2024-01-31',
    'limit': 30
}
 
response = requests.get(
    f'https://api.aloochat.ai/api/v1/analytics/agents/{agent_id}/daily-metrics',
    headers={'x-api-token': 'YOUR_API_TOKEN'},
    params=params
)
 
daily_metrics = response.json()
print('Daily metrics:', daily_metrics)

Company Analytics

cURL:

curl "https://api.aloochat.ai/api/v1/analytics/company/usage?granularity=daily&start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z" \
  -H "x-api-token: YOUR_API_TOKEN"

JavaScript:

const params = new URLSearchParams({
  granularity: 'daily',
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-01-31T23:59:59Z'
});
 
const response = await fetch(`https://api.aloochat.ai/api/v1/analytics/company/usage?${params}`, {
  headers: {
    'x-api-token': 'YOUR_API_TOKEN'
  }
});
 
const usageMetrics = await response.json();
console.log('Usage metrics:', usageMetrics);
console.log('Estimated cost:', usageMetrics.cost_estimate);

Python:

import requests
 
params = {
    'granularity': 'daily',
    'start_date': '2024-01-01T00:00:00Z',
    'end_date': '2024-01-31T23:59:59Z'
}
 
response = requests.get(
    'https://api.aloochat.ai/api/v1/analytics/company/usage',
    headers={'x-api-token': 'YOUR_API_TOKEN'},
    params=params
)
 
usage_metrics = response.json()
print('Usage metrics:', usage_metrics)
print('Estimated cost:', usage_metrics['cost_estimate'])

Get Company Insights

Get AI-generated insights and recommendations based on your company’s performance data.

cURL:

curl "https://api.aloochat.ai/api/v1/analytics/company/insights?days=30" \
  -H "x-api-token: YOUR_API_TOKEN"

JavaScript:

const params = new URLSearchParams({
  days: '30',
  insight_types: 'performance,usage,recommendation'
});
 
const response = await fetch(`https://api.aloochat.ai/api/v1/analytics/company/insights?${params}`, {
  headers: {
    'x-api-token': 'YOUR_API_TOKEN'
  }
});
 
const insights = await response.json();
console.log('Company insights:', insights);
 
// Process insights by severity
insights.insights.forEach(insight => {
  console.log(`${insight.severity.toUpperCase()}: ${insight.title}`);
  console.log(insight.description);
});

Python:

import requests
 
params = {
    'days': 30,
    'insight_types': ['performance', 'usage', 'recommendation']
}
 
response = requests.get(
    'https://api.aloochat.ai/api/v1/analytics/company/insights',
    headers={'x-api-token': 'YOUR_API_TOKEN'},
    params=params
)
 
insights = response.json()
print('Company insights:', insights)
 
# Process insights by severity
for insight in insights['insights']:
    print(f"{insight['severity'].upper()}: {insight['title']}")
    print(insight['description'])

Query Analysis

Get Query Distribution

Analyze query patterns and distributions across agents and time periods.

cURL:

curl "https://api.aloochat.ai/api/v1/analytics/query-distribution?agent_id=123e4567-e89b-12d3-a456-426614174000&top_n=20" \
  -H "x-api-token: YOUR_API_TOKEN"

JavaScript:

const params = new URLSearchParams({
  agent_id: '123e4567-e89b-12d3-a456-426614174000',
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-01-31T23:59:59Z',
  top_n: '20'
});
 
const response = await fetch(`https://api.aloochat.ai/api/v1/analytics/query-distribution?${params}`, {
  headers: {
    'x-api-token': 'YOUR_API_TOKEN'
  }
});
 
const queryDistribution = await response.json();
console.log('Query distribution:', queryDistribution);
 
// Show top query types
Object.entries(queryDistribution.distribution).forEach(([queryType, stats]) => {
  console.log(`${queryType}: ${stats.count} queries (${stats.percentage}%)`);
  console.log(`  Avg response time: ${stats.avg_response_time}ms`);
  console.log(`  Resolution rate: ${stats.resolution_rate}%`);
});

Python:

import requests
 
params = {
    'agent_id': '123e4567-e89b-12d3-a456-426614174000',
    'start_date': '2024-01-01T00:00:00Z',
    'end_date': '2024-01-31T23:59:59Z',
    'top_n': 20
}
 
response = requests.get(
    'https://api.aloochat.ai/api/v1/analytics/query-distribution',
    headers={'x-api-token': 'YOUR_API_TOKEN'},
    params=params
)
 
query_distribution = response.json()
print('Query distribution:', query_distribution)
 
# Show top query types
for query_type, stats in query_distribution['distribution'].items():
    print(f"{query_type}: {stats['count']} queries ({stats['percentage']}%)")
    print(f"  Avg response time: {stats['avg_response_time']}ms")
    print(f"  Resolution rate: {stats['resolution_rate']}%")

Response Schemas

Agent Interaction

{
  "id": "789e0123-e89b-12d3-a456-426614174002",
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "deployment_id": "456e7890-e89b-12d3-a456-426614174001",
  "conversation_id": "789e0123-e89b-12d3-a456-426614174002",
  "user_id": "012e3456-e89b-12d3-a456-426614174003",
  "company_id": "345e6789-e89b-12d3-a456-426614174004",
  "query_text": "What are your business hours?",
  "response_time_ms": 1250,
  "token_count_input": 45,
  "token_count_output": 78,
  "was_resolved": true,
  "created_at": "2024-01-15T10:30:00Z"
}

Performance Metrics

{
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "deployment_id": "456e7890-e89b-12d3-a456-426614174001",
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "total_interactions": 1250,
  "total_tokens_input": 45000,
  "total_tokens_output": 78000,
  "avg_response_time_ms": 1150.5,
  "resolution_rate": 0.87,
  "daily_metrics": [
    {
      "date": "2024-01-01",
      "total_interactions": 45,
      "avg_response_time_ms": 1200.0,
      "resolution_rate": 0.89
    }
  ]
}

Company Analytics

{
  "company_id": "345e6789-e89b-12d3-a456-426614174004",
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "total_interactions": 15750,
  "total_agents": 12,
  "total_deployments": 18,
  "avg_response_time_ms": 1087.3,
  "overall_resolution_rate": 0.84,
  "top_agents": [
    {
      "agent_id": "123e4567-e89b-12d3-a456-426614174000",
      "interactions": 1250,
      "resolution_rate": 0.87
    }
  ],
  "query_distribution": {
    "support": 4500,
    "billing": 3200,
    "technical": 2800
  }
}

Error Handling

The Analytics API uses standard HTTP status codes and returns detailed error messages:

{
  "error": "ValidationError",
  "message": "Invalid agent_id format",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00Z",
  "path": "/api/v1/analytics/interactions"
}

Common error codes:

  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API token)
  • 404 - Not Found (agent/resource not found)
  • 429 - Too Many Requests (rate limit exceeded)
  • 500 - Internal Server Error

Rate Limits

Analytics API endpoints are subject to rate limiting:

  • Standard endpoints: 100 requests per minute
  • Heavy analytics endpoints: 20 requests per minute
  • Insights generation: 5 requests per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248600

Warning: Rate limits are per API token. If you need higher limits, contact support.

ChatOverview