Telgea Developer Docs

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

The analytics report object

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

Field Type Description

usagerequired object One series per usage type, bucketed by the requested interval.

Show 3 child fields of usage

Field Type Description

datarequired array of RegionalIntervalUsage Data usage per interval, in bytes.

Show 2 child fields of data

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired RegionalUsage Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name.

Show 0 child fields of usage

Field	Type	Description

voicerequired array of LocationIntervalUsage Voice usage per interval, in seconds.

Show 2 child fields of voice

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

smsrequired array of LocationIntervalUsage SMS usage per interval, as a count.

Show 2 child fields of sms

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

metadatarequired object Highest, lowest and average interval for each series, so you need not compute them.

Show 3 child fields of metadata

Field Type Description

datarequired RegionalUsageMetadata Summary of the data series over the whole window.

Show 3 child fields of data

Field Type Description

highestrequired object The interval with the most usage in the window.

Show 2 child fields of highest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired RegionalUsage Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name.

Show 0 child fields of usage

Field	Type	Description

lowestrequired object The interval with the least usage in the window.

Show 2 child fields of lowest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired RegionalUsage Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name.

Show 0 child fields of usage

Field	Type	Description

averagerequired object Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name.

Show 1 child fields of average

Field	Type	Description
`total`required	number	Usage across every region, in bytes. `10485760`

voicerequired LocationUsageMetadata Summary of the voice or SMS series over the whole window.

Show 3 child fields of voice

Field Type Description

highestrequired object The interval with the most usage in the window.

Show 2 child fields of highest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

lowestrequired object The interval with the least usage in the window.

Show 2 child fields of lowest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

averagerequired object Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of average

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

smsrequired LocationUsageMetadata Summary of the voice or SMS series over the whole window.

Show 3 child fields of sms

Field Type Description

highestrequired object The interval with the most usage in the window.

Show 2 child fields of highest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

lowestrequired object The interval with the least usage in the window.

Show 2 child fields of lowest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

averagerequired object Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of average

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

Operations

GETGet aggregated usage analytics

Get aggregated usage analytics

GET/v1/analytics

Enterprise APIPartner 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 → Calls run against your live organization; there is no sandbox.

Parameters

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

Problems this endpoint can return

This endpoint returns no domain-specific problems.

Response fields

200 AnalyticsResponse

Field Type Description

usagerequired object One series per usage type, bucketed by the requested interval.

Show 3 child fields of usage

Field Type Description

datarequired array of RegionalIntervalUsage Data usage per interval, in bytes.

Show 2 child fields of data

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired RegionalUsage Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name.

Show 0 child fields of usage

Field	Type	Description

voicerequired array of LocationIntervalUsage Voice usage per interval, in seconds.

Show 2 child fields of voice

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

smsrequired array of LocationIntervalUsage SMS usage per interval, as a count.

Show 2 child fields of sms

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

metadatarequired object Highest, lowest and average interval for each series, so you need not compute them.

Show 3 child fields of metadata

Field Type Description

datarequired RegionalUsageMetadata Summary of the data series over the whole window.

Show 3 child fields of data

Field Type Description

highestrequired object The interval with the most usage in the window.

Show 2 child fields of highest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired RegionalUsage Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name.

Show 0 child fields of usage

Field	Type	Description

lowestrequired object The interval with the least usage in the window.

Show 2 child fields of lowest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired RegionalUsage Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name.

Show 0 child fields of usage

Field	Type	Description

averagerequired object Data usage for one interval: `total`, plus one property per region the usage was served in, keyed by region name.

Show 1 child fields of average

Field	Type	Description
`total`required	number	Usage across every region, in bytes. `10485760`

voicerequired LocationUsageMetadata Summary of the voice or SMS series over the whole window.

Show 3 child fields of voice

Field Type Description

highestrequired object The interval with the most usage in the window.

Show 2 child fields of highest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

lowestrequired object The interval with the least usage in the window.

Show 2 child fields of lowest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

averagerequired object Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of average

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

smsrequired LocationUsageMetadata Summary of the voice or SMS series over the whole window.

Show 3 child fields of sms

Field Type Description

highestrequired object The interval with the most usage in the window.

Show 2 child fields of highest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

lowestrequired object The interval with the least usage in the window.

Show 2 child fields of lowest

Field Type Description

intervalrequired

string

The bucket this usage falls in, as YYYY-MM-DD for a day or YYYY-MM for a month.

2026-09-11

usagerequired LocationUsage Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of usage

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

averagerequired object Voice or SMS usage for one interval, split by whether it stayed in the home market.

Show 3 child fields of average

Field	Type	Description
`local`required	number	Usage inside the home market. `1240`
`international`required	number	Usage to or from another country. `310`
`total`required	number	Local and international added together. `1550`

GET/v1/analytics

Request

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

Response

{
  "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
      }
    }
  }
}

GET/v1/analytics

Request

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

Response

{
  "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
      }
    }
  }
}

Need the raw schema? OpenAPI JSON