> ## 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 Organization

> Returns voice minutes aggregated per organization, with a per-agent breakdown

## Overview

Returns voice minutes aggregated per organization for the requested date range, including a nested per-agent breakdown. If neither `organization_ids` nor `reseller_ids` is provided, all organizations the caller has access to are returned.

## 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="organization_ids" type="string | string[]">
  Optional filter by organization UUIDs. Provide either:

  * A comma-separated list: `organization_ids=uuid1,uuid2`
  * Or repeated bracketed params: `organization_ids[]=uuid1&organization_ids[]=uuid2`
</ParamField>

<ParamField query="reseller_ids" type="string | string[]">
  Optional filter by reseller UUIDs. Same formats as `organization_ids`. Combined with `organization_ids`, both filters are applied.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.telzino.com/v1/reports/minutes-by-organization?start_date=2026-04-01&end_date=2026-04-30" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

  # Filter by specific organizations
  curl "https://api.telzino.com/v1/reports/minutes-by-organization?start_date=2026-04-01&end_date=2026-04-30&organization_ids=123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

  # Filter by reseller
  curl "https://api.telzino.com/v1/reports/minutes-by-organization?start_date=2026-04-01&end_date=2026-04-30&reseller_ids=323e4567-e89b-12d3-a456-426614174999" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    start_date: '2026-04-01',
    end_date: '2026-04-30'
  });

  const response = await fetch(
    `https://api.telzino.com/v1/reports/minutes-by-organization?${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-organization',
      params={
          'start_date': '2026-04-01',
          'end_date': '2026-04-30'
      },
      headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
  )

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "organization_id": "123e4567-e89b-12d3-a456-426614174000",
        "organization_name": "Acme Solar",
        "reseller_id": "323e4567-e89b-12d3-a456-426614174999",
        "reseller_name": "Acme Partners",
        "total_voice_minutes": 512.7,
        "agent_count": 2,
        "agents": [
          {
            "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "agent_name": "Customer Support Agent",
            "voice_minutes": 370.4
          },
          {
            "agent_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "agent_name": "Booking Agent",
            "voice_minutes": 142.3
          }
        ]
      }
    ],
    "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 401 theme={null}
  {
    "error": "unauthorized",
    "error_description": "Account context not found"
  }
  ```
</ResponseExample>

<Info>
  When a caller has no resellers, when the `reseller_ids` filter excludes all accessible resellers, or when no organizations match the filters, the endpoint returns `200` with an empty `data` array.
</Info>

## Response Fields

### `data`

Array of per-organization usage entries:

| Field                 | Type          | Description                                               |
| --------------------- | ------------- | --------------------------------------------------------- |
| `organization_id`     | string (UUID) | Organization ID                                           |
| `organization_name`   | string        | Organization name (falls back to internal ID if unset)    |
| `reseller_id`         | string (UUID) | Reseller that owns the organization                       |
| `reseller_name`       | string        | Reseller name (falls back to internal ID if unset)        |
| `total_voice_minutes` | number        | Total voice minutes for the organization in the range     |
| `agent_count`         | number        | Number of agents under this organization                  |
| `agents`              | array         | Per-agent breakdown, sorted by `voice_minutes` descending |

### `agents[]`

| Field           | Type          | Description                                                      |
| --------------- | ------------- | ---------------------------------------------------------------- |
| `agent_id`      | string (UUID) | Agent ID                                                         |
| `agent_name`    | string        | Agent name (falls back to `external_id` or internal ID if unset) |
| `voice_minutes` | number        | Voice minutes for this agent 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`   |