Skip to navigation
EndpointList endpoint data usage per data plan

List endpoint data usage per data plan

Required permissions Beta Learn more

Endpoint.Stats + Get +3 endpoints

Roles: Administrator User Observer

Returns the data usage of each endpoint in your organization against its data plan, with endpoints ranked by total volume. Use it to find the endpoints that use up a data plan’s allowance, the endpoints without a data plan, and the endpoints with traffic outside the coverage areas of their data plan. In the API, the data plan is the data_allowance object.

Only endpoints with data usage in the requested period are returned. Volumes are in MB and include zero-rated traffic. The zero-rated portion is reported separately, so the billable volume is volume_mb minus volume_zero_rated_mb.

  • covered is the traffic in the coverage areas of the data plan. This traffic counts against the allowance.
  • uncovered is the traffic outside those coverage areas. For an endpoint without a data plan, all traffic is uncovered.
  • covered.volume_mb plus uncovered.volume_mb always equals volume_mb.

Each rated_cost is the cost at list price, not the invoiced amount.

For a pooled data plan (data_allowance.pooled is true), volume_per_sim_mb is the volume each SIM contributes to the pooled allowance of the organization, not a quota for the endpoint.

sim_id, tariff_profile_id, and data_allowance describe the endpoint on its most recent day with data usage in the requested period.

Date range

start_date and end_date are inclusive UTC days:

  • Neither set: the current month up to today.
  • Only start_date: from start_date up to today. If that period is longer than 31 days, also set end_date.
  • Only end_date: from the first day of the month of end_date up to end_date.
  • Both set: the period as given. It can be at most 31 days long, and start_date can’t be after end_date.

start_date can’t be earlier than the first day of the month 6 months before the current month. For example, on October 26, 2026, the earliest start_date is 2026-04-01.

Usage data comes from daily usage records, which can lag behind live traffic by up to 3 days.

Authentication

AuthorizationBearer

An auth_token should be provided to authenticate a session.

To obtain an auth_token, see the /api/v1/authenticate POST request.

Query parameters

start_datestringOptionalformat: "date"

First day of the period, in YYYY-MM-DD format (UTC, inclusive). See the endpoint description for the date range rules.

end_datestringOptionalformat: "date"

Last day of the period, in YYYY-MM-DD format (UTC, inclusive). See the endpoint description for the date range rules.

qstringOptionalformat: "(endpoint_id|sim_id|data_allowance_id|tariff_profile_id|tariff_id|pooled|has_allowance):.+"

Filters endpoints by field value. Use <field>:<criteria> format. Combine filters on different fields with commas, and separate multiple values for one field with || (for example, data_allowance_id:49||51).

Fields:

  • endpoint_id - Endpoint ID
  • sim_id - SIM ID
  • data_allowance_id - Data plan ID
  • tariff_profile_id - Tariff profile ID
  • tariff_id - Tariff ID
  • pooled - true for endpoints on a pooled data plan, false for endpoints on a per-SIM data plan
  • has_allowance - true for endpoints with a data plan, false for endpoints without one
sortstringOptionalformat: "^[+-]?(volume|covered_volume|uncovered_volume|uncovered_cost|zero_rated_volume|last_active)(,[+-]?(volume|covered_volume|uncovered_volume|uncovered_cost|zero_rated_volume|last_active))*$"

Sorts endpoints by field value. Use <operator><field> format. Combine multiple sort fields with commas (for example, -uncovered_volume,-volume).

Operators:

  • - descending (highest value or most recent date first)
  • + ascending (lowest value or oldest date first)

Fields:

  • volume - volume_mb
  • covered_volume - covered.volume_mb
  • uncovered_volume - uncovered.volume_mb
  • uncovered_cost - uncovered.rated_cost
  • zero_rated_volume - volume_zero_rated_mb
  • last_active - last_active_date

Defaults to ascending order if no operator is specified. Defaults to -volume if sort isn’t set. Endpoints with identical values are sorted by ascending endpoint_id.

pageintegerOptional>=1Defaults to 1
Page number to retrieve. Starts at 1.
per_pageintegerOptional1-100Defaults to 25
Number of endpoints to return per page. Values above 100 are treated as 100.

Response headers

X-Count-Per-PageintegerOptional
Number of endpoints per page.
X-Current-PageintegerOptional
Current page number.
X-Total-CountintegerOptional
Total number of endpoints matching the query.
X-Total-PagesintegerOptional
Total number of pages.
X-FilterstringOptional

Applied filter criteria from the q parameter. Only present when q is set.

X-SortstringOptional

Value of the sort parameter, or id when sort isn’t set. The applied default order is still -volume.

Response

Returns an array of endpoints ranked by total volume. Pagination metadata is included in the response headers.
organisation_idinteger
ID of the organization that owns the endpoint.
endpoint_idinteger
Endpoint ID.
sim_idinteger or null
ID of the SIM in the endpoint on its most recent day with data usage in the requested period.
tariff_profile_idinteger or null
ID of the tariff profile assigned to the endpoint on its most recent day with data usage in the requested period.
data_allowanceobject or null

Data plan of the endpoint on its most recent day with data usage in the requested period. null when the endpoint has no data plan, in which case all traffic is rated at list price.

volume_mbdouble

Total volume in MB in the requested period, including zero-rated traffic.

volume_tx_mbdouble

Uplink (endpoint to network) portion of volume_mb, in MB.

volume_rx_mbdouble

Downlink (network to endpoint) portion of volume_mb, in MB.

volume_zero_rated_mbdouble

Zero-rated (not billed) portion of volume_mb, in MB.

coveredobject
Traffic in the coverage areas of the data plan. This traffic counts against the allowance.
uncoveredobject
Traffic outside the coverage areas of the data plan, or all traffic when the endpoint has no data plan.
currencyobject or null

Currency of rated_cost, fee, and excess_rate_per_mb.

last_active_datestringformat: "date"

Most recent day (UTC) with data usage in the requested period, in YYYY-MM-DD format.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error