Skip to content

Get usage over period

Request

This endpoint retrieves detailed usage data for a specific subscription identified by its ICCID over a specified time period.

Important constraints:

  • The maximum period is 7 days, including both the start and end dates
  • The start date must come before the end date
  • Requests that violate these constraints will be rejected

The response includes:

  • Total usage aggregated across the entire period
  • Daily breakdown of usage with country-level details
  • Country-level aggregation for the entire period
Security
ApiKeyAuth
Path
iccidstringrequired

The ICCID of the subscription

Example:8948010000094659307
Bodyapplication/jsonrequired
periodobjectrequired

The time period for which to retrieve usage data. Maximum period is 7 days including start and end dates.

POST
/v3/subscriptions/{iccid}/usage-over-period
curl -i -X POST \
  'https://api.tellisim.com/v3/subscriptions/8948010000094659307/usage-over-period?key=YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "period": {
      "start": "2026-04-13",
      "end": "2026-04-19"
    }
  }'

Responses

Successful response containing usage data for the specified period

Bodyapplication/json
errorbooleanrequired

Indicates whether there was an error processing the request

Example:false
dataobjectrequired

Contains the usage data for the specified period

Response
{
  "error": false,
  "data": {
    "iccid": "8948010000094661394",
    "start_date": "2026-04-30",
    "end_date": "2026-05-01",
    "total_usage": { … },
    "usage_per_day": [ … ],
    "usage_per_country": [ … ]
  }
}