---
title: "Get aggregated usage analytics"
method: GET
path: "/v1/analytics"
tags: ["Analytics"]
---

# Get aggregated usage analytics

`GET /v1/analytics`

## Request

- Base URL: `https://api.telgea.com`
- URL: `https://api.telgea.com/v1/analytics`
- Auth: API key in header `x-api-key`

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.

## Query parameters

- `startDate` string, date, required: Inclusive start of the reporting window (YYYY-MM-DD).
- `endDate` string, date, required: Inclusive end of the reporting window (YYYY-MM-DD).
- `interval` 'month' | 'day', required: Aggregation bucket size
- `userId` string, uuid: Restrict to one end-user your organization owns.
- `msisdn` string: Restrict to a single number.
- `countryIsoCode` string: Restrict to usage served in one country.
- `orderBy` 'asc' | 'desc': Order the returned intervals ascending or descending by time

## Response `200`

Aggregated usage grouped by interval, with per-channel metadata.

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

## Other responses

- `400`: Request failed schema validation
- `401`: Missing or invalid API key in the X-API-Key header
- `403`: The API key lacks the analytics:read scope
- `429`: The API key has used its request quota for the current window. `Retry-After` says how many seconds until it resets.
- `500`: Internal server error. Contact support if this persists.

---

[API](https://skmtc.dev/telgea/apis/telgea-api.md) - [All operations](https://skmtc.dev/telgea/apis/telgea-api/llms.txt) - [OpenAPI document](https://skmtc.dev/telgea/apis/telgea-api/revisions/4e8f8c04fe9e?raw)