Analytics - Voice Agent API - Voice AI Developer Docs

Monitor agent performance, call history, and usage statistics.

Prerequisites: API key, deployed agents

Stats Summary

Get a summary of statistics for all your agents, including call counts and durations.

import requests

response = requests.get(
    'https://dev.voice.ai/api/v1/agent/stats-summary',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

summary = response.json()
print(f"Total agents: {summary['total_agents']}")
print(f"Active agents: {summary['active_agents']}")
for agent in summary['agent_stats']:
    print(f"{agent['agent_name']}: {agent['call_count']} calls")

curl -X GET "https://dev.voice.ai/api/v1/agent/stats-summary" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://dev.voice.ai/api/v1/agent/stats-summary', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const summary = await response.json();
console.log(`Total agents: ${summary.total_agents}`);
console.log(`Active agents: ${summary.active_agents}`);
summary.agent_stats.forEach((agent: any) => {
  console.log(`${agent.agent_name}: ${agent.call_count} calls`);
});

Call History

Retrieve paginated call history with optional filtering by agent ID(s) and date range. You can filter by a single agent ID or multiple agent IDs. See the Call History endpoint for details. Each call history item includes:

Basic Info: id, agent_id, agent_name, call_timestamp, call_duration_seconds
Billing: credits_used - Credits consumed for the call
Metadata: has_transcript, call_type (e.g., 'web', 'sip_inbound', 'sip_outbound', 'test', 'playground')
Phone Numbers: from_number, to_number (for phone calls)
Transcript Data: transcription_summary (AI-generated summary), transcription_stats (message counts and statistics)

import requests

response = requests.get(
    'https://dev.voice.ai/api/v1/agent/call-history',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={
        'page': 1,
        'limit': 20,
        'agent_ids': ['agent_123', 'agent_456'],  # Optional: single ID or list of IDs
        'start_date': '2024-01-01T00:00:00+00:00',  # Optional: ISO format UTC
        'end_date': '2024-01-31T23:59:59+00:00'  # Optional: ISO format UTC
    }
)

data = response.json()
for call in data['items']:
    print(f"Call {call['id']}: {call['call_duration_seconds']}s - {call['call_type']} - {call['credits_used']} credits")

# Single agent ID
curl -X GET "https://dev.voice.ai/api/v1/agent/call-history?page=1&limit=20&agent_ids=agent_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Multiple agent IDs
curl -X GET "https://dev.voice.ai/api/v1/agent/call-history?page=1&limit=20&agent_ids=agent_123&agent_ids=agent_456" \
  -H "Authorization: Bearer YOUR_API_KEY"

// Single agent ID
const params = new URLSearchParams({
  page: '1',
  limit: '20',
  agent_ids: 'agent_123'  // Optional: single ID
});

// Multiple agent IDs
const paramsMultiple = new URLSearchParams();
paramsMultiple.append('page', '1');
paramsMultiple.append('limit', '20');
paramsMultiple.append('agent_ids', 'agent_123');
paramsMultiple.append('agent_ids', 'agent_456');

// Using single agent ID
const response = await fetch(`https://dev.voice.ai/api/v1/agent/call-history?${params}`, {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

// Using multiple agent IDs
const responseMultiple = await fetch(`https://dev.voice.ai/api/v1/agent/call-history?${paramsMultiple}`, {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
data.items.forEach((call: any) => {
  console.log(`Call ${call.id}: ${call.call_duration_seconds}s - ${call.call_type} - ${call.credits_used} credits`);
});

Response:

{
  "items": [
    {
      "id": 123,
      "agent_id": "agent_123",
      "agent_name": "Support Agent",
      "call_timestamp": "2024-01-15T10:30:00Z",
      "call_duration_seconds": 180.5,
      "credits_used": 90.25,
      "has_transcript": true,
      "call_type": "sip_inbound",
      "from_number": "+14155551234",
      "to_number": "+14155555678",
      "transcription_summary": "Customer called about order status...",
      "transcription_stats": {
        "total_messages": 45,
        "agent_messages": 23,
        "user_messages": 22
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 63,
    "total_items": 1250,
    "limit": 20,
    "has_next": true,
    "has_prev": false
  }
}

Call Transcript

Retrieve a presigned URL to download the transcript for a specific call using the call ID from call history. The transcript is stored as a JSON file in S3. See the Get Call Transcript URL endpoint for details.

import requests

response = requests.get(
    f'https://dev.voice.ai/api/v1/agent/call-history/{call_id}/transcript',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

data = response.json()
transcript_url = data['url']
print(f"Transcript URL: {transcript_url}")

# Download the transcript
transcript_response = requests.get(transcript_url)
transcript = transcript_response.json()
print(f"Call ID: {transcript['call_id']}")

# Get presigned URL
curl -X GET "https://dev.voice.ai/api/v1/agent/call-history/{call_id}/transcript" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Download transcript from the returned URL
curl "https://s3-presigned-url..."

const response = await fetch(`https://dev.voice.ai/api/v1/agent/call-history/${callId}/transcript`, {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
const transcriptUrl = data.url;

// Download the transcript
const transcriptResponse = await fetch(transcriptUrl);
const transcript = await transcriptResponse.json();
console.log(`Call ID: ${transcript.call_id}`);

Response:

{
  "url": "https://s3.amazonaws.com/bucket/transcripts/123.json?X-Amz-Algorithm=..."
}

The presigned URL is valid for a limited time. Download the JSON file to access the full transcript data, which includes call metadata and message history.

Call Recording

Retrieve the merged call recording status for a specific call using the call ID from call history. When the recording is ready, the endpoint returns a presigned URL to a muxed MP3 file. If the recording artifacts are still being processed, the endpoint returns processing. See the Call Recording endpoint for details.

import requests

response = requests.get(
    f'https://dev.voice.ai/api/v1/agent/call-history/{call_id}/recording',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

data = response.json()
print(f"Recording status: {data['status']}")

if data['status'] == 'ready':
    recording_url = data['url']
    print(f"Recording URL: {recording_url}")

curl -X GET "https://dev.voice.ai/api/v1/agent/call-history/{call_id}/recording"   -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(`https://dev.voice.ai/api/v1/agent/call-history/${callId}/recording`, {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
console.log(`Recording status: ${data.status}`);

if (data.status === 'ready') {
  console.log(`Recording URL: ${data.url}`);
}

Responses:

{
  "status": "processing",
  "url": null
}

{
  "status": "ready",
  "url": "https://s3.amazonaws.com/bucket/recordings/123.mp3?X-Amz-Algorithm=..."
}

Possible status values:

ready: Recording is available and url is populated.
processing: Recording artifacts are still being merged.
not_recorded: No recording exists for that call.

Use Cases

Performance Monitoring: Track call volumes, durations, and success rates
Cost Analysis: Monitor credit usage and optimize agent configurations
Quality Assurance: Review transcripts to improve agent prompts and responses
Agent Comparison: Compare performance across different agents

Next Steps

Agent Quickstart - Create your first agent
API Reference - Complete API reference

Get started

Text-to-Speech

Voice Agents

SDKs

Analytics - Voice Agent API

Stats Summary

Call History

Call Transcript

Call Recording

Use Cases

Next Steps

​Stats Summary

​Call History

​Call Transcript

​Call Recording

​Use Cases

​Next Steps

Stats Summary

Call History

Call Transcript

Call Recording

Use Cases

Next Steps