# Analytics

Voice, SMS and data consumption aggregated per interval, with the highest, lowest and average across the window. For reporting and dashboards.

> Enterprise API · https://developer.telgea.com/docs/enterprise/api/analytics

## The analytics report object {#object}

Aggregated voice, SMS, and data consumption for reporting and dashboards.

| Field | Type | Description |
| --- | --- | --- |
| `usage` | object (required) | One series per usage type, bucketed by the requested interval. |
| `usage.data` | array of RegionalIntervalUsage (required) | Data usage per interval, in bytes. |
| `usage.data.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `usage.data.usage` | RegionalUsage (required) | Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name. |
| `usage.voice` | array of LocationIntervalUsage (required) | Voice usage per interval, in seconds. |
| `usage.voice.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `usage.voice.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `usage.voice.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `usage.voice.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `usage.voice.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `usage.sms` | array of LocationIntervalUsage (required) | SMS usage per interval, as a count. |
| `usage.sms.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `usage.sms.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `usage.sms.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `usage.sms.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `usage.sms.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata` | object (required) | Highest, lowest and average interval for each series, so you need not compute them. |
| `metadata.data` | RegionalUsageMetadata (required) | Summary of the data series over the whole window. |
| `metadata.data.highest` | object (required) | The interval with the most usage in the window. |
| `metadata.data.highest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.data.highest.usage` | RegionalUsage (required) | Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name. |
| `metadata.data.lowest` | object (required) | The interval with the least usage in the window. |
| `metadata.data.lowest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.data.lowest.usage` | RegionalUsage (required) | Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name. |
| `metadata.data.average` | object (required) | Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name. |
| `metadata.data.average.total` | number (required) | Usage across every region, in bytes. Example: `10485760` |
| `metadata.voice` | LocationUsageMetadata (required) | Summary of the voice or SMS series over the whole window. |
| `metadata.voice.highest` | object (required) | The interval with the most usage in the window. |
| `metadata.voice.highest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.voice.highest.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.voice.highest.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.voice.highest.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.voice.highest.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.voice.lowest` | object (required) | The interval with the least usage in the window. |
| `metadata.voice.lowest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.voice.lowest.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.voice.lowest.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.voice.lowest.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.voice.lowest.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.voice.average` | object (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.voice.average.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.voice.average.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.voice.average.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.sms` | LocationUsageMetadata (required) | Summary of the voice or SMS series over the whole window. |
| `metadata.sms.highest` | object (required) | The interval with the most usage in the window. |
| `metadata.sms.highest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.sms.highest.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.sms.highest.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.sms.highest.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.sms.highest.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.sms.lowest` | object (required) | The interval with the least usage in the window. |
| `metadata.sms.lowest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.sms.lowest.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.sms.lowest.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.sms.lowest.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.sms.lowest.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.sms.average` | object (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.sms.average.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.sms.average.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.sms.average.total` | number (required) | Local and international added together. Example: `1550` |

## Operations

- `GET` [Get aggregated usage analytics](#get-aggregated-usage-analytics)

### Get aggregated usage analytics {#get-aggregated-usage-analytics}

`GET /v1/analytics` · Enterprise API + Partner API

Returns voice, SMS, and data consumption for your organization, aggregated into per-`interval` totals with highest / lowest / average metadata across the window.

Use this for reporting and dashboards. When you need individual events — to bill on or to act on one customer's usage — use `GET /v1/usage` instead. Totals lag the network by the same delay as the usage feed.

Requires the permission `analytics:read` on the key.

[Try it in the playground](https://developer.telgea.com/playground#tag/analytics/GET/v1/analytics). Calls run against your live organization; there is no sandbox.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `startDate` | query | string (date) (required) | Inclusive start of the reporting window (YYYY-MM-DD). Example: `2026-09-01` |
| `endDate` | query | string (date) (required) | Inclusive end of the reporting window (YYYY-MM-DD). Example: `2026-09-30` |
| `interval` | query | enum (required) | Aggregation bucket size Example: `day` |
| `userId` | query | string (uuid) | Restrict to one end-user your organization owns. Example: `9c1f2a6e-3b7d-4e0a-8f21-5d6c7b8a9e01` |
| `msisdn` | query | string | Restrict to a single number. Example: `+4520123456` |
| `countryIsoCode` | query | string | Restrict to usage served in one country. Example: `DK` |
| `orderBy` | query | enum | Order the returned intervals ascending or descending by time Example: `asc` |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| `200` | Aggregated usage grouped by interval, with per-channel metadata. | `AnalyticsResponse` |
| `400` | Request failed schema validation | none |
| `401` | Missing or invalid API key in the X-API-Key header | `UnauthorizedError` |
| `403` | The API key lacks the analytics:read scope | `ForbiddenError` |
| `429` | The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets. | `TooManyRequestsError` |
| `500` | Internal server error. Contact support if this persists. | `InternalError` |

**Response fields (200, AnalyticsResponse)**

| Field | Type | Description |
| --- | --- | --- |
| `usage` | object (required) | One series per usage type, bucketed by the requested interval. |
| `usage.data` | array of RegionalIntervalUsage (required) | Data usage per interval, in bytes. |
| `usage.data.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `usage.data.usage` | RegionalUsage (required) | Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name. |
| `usage.voice` | array of LocationIntervalUsage (required) | Voice usage per interval, in seconds. |
| `usage.voice.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `usage.voice.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `usage.voice.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `usage.voice.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `usage.voice.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `usage.sms` | array of LocationIntervalUsage (required) | SMS usage per interval, as a count. |
| `usage.sms.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `usage.sms.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `usage.sms.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `usage.sms.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `usage.sms.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata` | object (required) | Highest, lowest and average interval for each series, so you need not compute them. |
| `metadata.data` | RegionalUsageMetadata (required) | Summary of the data series over the whole window. |
| `metadata.data.highest` | object (required) | The interval with the most usage in the window. |
| `metadata.data.highest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.data.highest.usage` | RegionalUsage (required) | Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name. |
| `metadata.data.lowest` | object (required) | The interval with the least usage in the window. |
| `metadata.data.lowest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.data.lowest.usage` | RegionalUsage (required) | Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name. |
| `metadata.data.average` | object (required) | Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name. |
| `metadata.data.average.total` | number (required) | Usage across every region, in bytes. Example: `10485760` |
| `metadata.voice` | LocationUsageMetadata (required) | Summary of the voice or SMS series over the whole window. |
| `metadata.voice.highest` | object (required) | The interval with the most usage in the window. |
| `metadata.voice.highest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.voice.highest.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.voice.highest.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.voice.highest.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.voice.highest.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.voice.lowest` | object (required) | The interval with the least usage in the window. |
| `metadata.voice.lowest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.voice.lowest.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.voice.lowest.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.voice.lowest.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.voice.lowest.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.voice.average` | object (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.voice.average.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.voice.average.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.voice.average.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.sms` | LocationUsageMetadata (required) | Summary of the voice or SMS series over the whole window. |
| `metadata.sms.highest` | object (required) | The interval with the most usage in the window. |
| `metadata.sms.highest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.sms.highest.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.sms.highest.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.sms.highest.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.sms.highest.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.sms.lowest` | object (required) | The interval with the least usage in the window. |
| `metadata.sms.lowest.interval` | string (required) | The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month. Example: `"2026-09-11"` |
| `metadata.sms.lowest.usage` | LocationUsage (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.sms.lowest.usage.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.sms.lowest.usage.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.sms.lowest.usage.total` | number (required) | Local and international added together. Example: `1550` |
| `metadata.sms.average` | object (required) | Voice or SMS usage for one interval, split by whether it stayed in the home market. |
| `metadata.sms.average.local` | number (required) | Usage inside the home market. Example: `1240` |
| `metadata.sms.average.international` | number (required) | Usage to or from another country. Example: `310` |
| `metadata.sms.average.total` | number (required) | Local and international added together. Example: `1550` |

**Example request**

```bash
curl -X GET "https://api.telgea.com/v1/analytics" \
  -H "x-api-key: $TELGEA_API_KEY"
```

**Response 200**

```json
{
  "usage": {
    "data": [
      {
        "interval": "2026-09-11",
        "usage": {
          "total": 10485760,
          "Europe": 9437184,
          "North America": 1048576
        }
      },
      {
        "interval": "2026-09-12",
        "usage": {
          "total": 524288,
          "Europe": 524288
        }
      }
    ],
    "voice": [
      {
        "interval": "2026-09-11",
        "usage": {
          "local": 1240,
          "international": 310,
          "total": 1550
        }
      },
      {
        "interval": "2026-09-12",
        "usage": {
          "local": 90,
          "international": 0,
          "total": 90
        }
      }
    ],
    "sms": [
      {
        "interval": "2026-09-11",
        "usage": {
          "local": 12,
          "international": 3,
          "total": 15
        }
      },
      {
        "interval": "2026-09-12",
        "usage": {
          "local": 1,
          "international": 0,
          "total": 1
        }
      }
    ]
  },
  "metadata": {
    "data": {
      "highest": {
        "interval": "2026-09-11",
        "usage": {
          "total": 10485760,
          "Europe": 9437184,
          "North America": 1048576
        }
      },
      "lowest": {
        "interval": "2026-09-12",
        "usage": {
          "total": 524288,
          "Europe": 524288
        }
      },
      "average": {
        "total": 5505024
      }
    },
    "voice": {
      "highest": {
        "interval": "2026-09-11",
        "usage": {
          "local": 1240,
          "international": 310,
          "total": 1550
        }
      },
      "lowest": {
        "interval": "2026-09-12",
        "usage": {
          "local": 90,
          "international": 0,
          "total": 90
        }
      },
      "average": {
        "local": 665,
        "international": 155,
        "total": 820
      }
    },
    "sms": {
      "highest": {
        "interval": "2026-09-11",
        "usage": {
          "local": 12,
          "international": 3,
          "total": 15
        }
      },
      "lowest": {
        "interval": "2026-09-12",
        "usage": {
          "local": 1,
          "international": 0,
          "total": 1
        }
      },
      "average": {
        "local": 6.5,
        "international": 1.5,
        "total": 8
      }
    }
  }
}
```