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

# Minutes by Agent

> Returns voice minutes and call counts aggregated per agent for a date range

## Overview

Returns per-agent voice minutes and call counts for the requested date range. Only agents owned by the authenticated account are returned; unknown or cross-account agent IDs are filtered out.

## Query Parameters

<ParamField query="start_date" type="string" required>
  Start of the date range in `YYYY-MM-DD` format (e.g., `2026-04-01`)
</ParamField>

<ParamField query="end_date" type="string" required>
  End of the date range in `YYYY-MM-DD` format (e.g., `2026-04-30`)
</ParamField>

<ParamField query="agent_ids" type="string | string[]" required>
  One or more agent UUIDs. Provide either:

  * A comma-separated list: `agent_ids=uuid1,uuid2`
  * Or repeated bracketed params: `agent_ids[]=uuid1&agent_ids[]=uuid2`

  At least one agent UUID is required.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.telzino.com/v1/reports/minutes-by-agent?start_date=2026-04-01&end_date=2026-04-30&agent_ids=123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    start_date: '2026-04-01',
    end_date: '2026-04-30',
    agent_ids: '123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001'
  });

  const response = await fetch(
    `https://api.telzino.com/v1/reports/minutes-by-agent?${params}`,
    { headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' } }
  );

  const { data, period } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.telzino.com/v1/reports/minutes-by-agent',
      params={
          'start_date': '2026-04-01',
          'end_date': '2026-04-30',
          'agent_ids': '123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001'
      },
      headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
  )

  report = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "agent_id": "123e4567-e89b-12d3-a456-426614174000",
        "agent_name": "Customer Support Agent",
        "reseller_name": "Acme Partners",
        "total_minutes": 324.5,
        "call_count": 87
      },
      {
        "agent_id": "223e4567-e89b-12d3-a456-426614174001",
        "agent_name": "Booking Agent",
        "reseller_name": "Acme Partners",
        "total_minutes": 142.1,
        "call_count": 33
      }
    ],
    "period": {
      "start_date": "2026-04-01",
      "end_date": "2026-04-30"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "invalid_request",
    "details": [
      {
        "code": "invalid_string",
        "message": "Invalid date format (use YYYY-MM-DD)",
        "path": ["start_date"]
      }
    ]
  }
  ```

  ```json 404 theme={null}
  {
    "error": "not_found",
    "error_description": "No matching agents found for this account"
  }
  ```
</ResponseExample>

## Response Fields

### `data`

Array of per-agent usage entries:

| Field           | Type          | Description                                                        |
| --------------- | ------------- | ------------------------------------------------------------------ |
| `agent_id`      | string (UUID) | Agent ID                                                           |
| `agent_name`    | string        | Agent name (falls back to `external_id` or internal ID if unset)   |
| `reseller_name` | string        | Reseller that owns the agent's organization, or `-` if unavailable |
| `total_minutes` | number        | Total voice minutes in the range                                   |
| `call_count`    | number        | Number of calls in the range                                       |

### `period`

| Field        | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| `start_date` | string | Echoes the request's `start_date` |
| `end_date`   | string | Echoes the request's `end_date`   |