Skip to navigation
Management APIReports

Get usage report

Returns meter-level usage aggregated by set granularity over the specified date range.

  • Can be filtered by projectNames, paymentMethodIds or meterNames.
  • Maximum date range depends on granularity: 31 days (hour), 1 year (day), unlimited (week, month, year).
  • Day boundaries use UTC; startDate is inclusive and endDate is exclusive (previously also inclusive).
  • To get a monthly report for January, use startDate=2026-01-01 and endDate=2026-02-01.
  • The response include date and date_processed fields. date is the time when the usage happened, while date_processed is when the usage was ingested into our system and processed for billing purposes.
  • Set filterOnReportedDate=true to filter by date_processed instead of date. This might include usage that occurred before the startDate if it was processed during the date range.
  • Set format=csv and download=true to receive a file download.

RBAC Capability Required: core.customer.get

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
endDatedateRequired

End date of the usage report (exclusive). This use to be inclusive. To get a full month of usage, set both startDate and endDate to the first of the month. Maximum range depends on granularity: 31 days for 'hour', 1 year for 'day', unlimited for 'week', 'month', or 'year'.",

startDatedateRequired

Start date of the usage report (inclusive).

downloadbooleanOptionalDefaults to false
When true, sets response headers to prompt a browser file download.
filterOnReportedDatebooleanOptionalDefaults to false

When true, filters usage by report_time (when the usage was charged) rather than sample_time (when it occurred). Useful for reconciling against invoice dates. Defaults to false.

formatenumOptionalDefaults to json
Response format. Either 'json' or 'csv'. Defaults to 'json'.
Allowed values:
granularityenumOptionalDefaults to day
Time bucket for aggregation. Defaults to 'day'.
Allowed values:
groupBylist of stringsOptional

Fields to group results by. Only 'meter' is currently valid. Defaults to ['meter'].

meterNameslist of stringsOptional
Filter results to the specified meter names.
paymentMethodIdslist of stringsOptional
Filter results to the specified payment method IDs. Mutually exclusive with projectNames.
projectNameslist of stringsOptional
Filter results to the specified project names. Mutually exclusive with paymentMethodIds.

Response

OK
supplementalobject
Metadata pertaining to the query.
valuelist of objectsRead-only
The usage data per day per meter

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error