> ## Documentation Index
> Fetch the complete documentation index at: https://voice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics - Voice Agent API

> Monitor Voice.ai agent performance with the Analytics API. Access call history, track credit usage, and retrieve AI-generated transcripts and conversation summaries

Monitor agent performance, call history, and usage statistics.

<Info>
  **Prerequisites**: [API key](/docs/guides/authentication), deployed agents
</Info>

## Stats Summary

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

<CodeGroup>
  ```python Python theme={null}
  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")
  ```

  ```bash cURL theme={null}
  curl -X GET "https://dev.voice.ai/api/v1/agent/stats-summary" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  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`);
  });
  ```
</CodeGroup>

## 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](/docs/api-reference/agent-analytics/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)

<CodeGroup>
  ```python Python theme={null}
  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")
  ```

  ```bash cURL theme={null}
  # 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"
  ```

  ```typescript TypeScript theme={null}
  // 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`);
  });
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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](/docs/api-reference/agent-analytics/get-call-transcript-url) endpoint for details.

<CodeGroup>
  ```python Python theme={null}
  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']}")
  ```

  ```bash cURL theme={null}
  # 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..."
  ```

  ```typescript TypeScript theme={null}
  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}`);
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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](/docs/api-reference/agent-analytics/call-recording) endpoint for details.

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

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

  ```typescript TypeScript theme={null}
  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}`);
  }
  ```
</CodeGroup>

**Responses:**

```json theme={null}
{
  "status": "processing",
  "url": null
}
```

```json theme={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](/docs/guides/voice-agents/quickstart) - Create your first agent
* [API Reference](/docs/api-reference) - Complete API reference