Get usage report

post https://app.mk.io/api/v1/organization/reports/usage

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.

Authentication

Authorization Bearer

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

Request

This endpoint expects an object.

downloadbooleanOptionalDefaults to false
When true, sets response headers to prompt a browser file download.
endDatestringRequiredformat: date
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'.",
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:jsoncsv
granularityenumOptionalDefaults to day
Time bucket for aggregation. Defaults to 'day'.
Allowed values:yearmonthweekdayhour
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.
startDatestringRequiredformat: date
Start date of the usage report (inclusive).

Response

200 OK
supplementalobjectSupplementalDataRequired
Metadata pertaining to the query.
Show 8 propertiesHide 8 properties
downloadbooleanRequired
Whether browser was indicated to download file
endstringRequiredformat: date
The end date of the query.
filtersobjectSupplementalFiltersDataRequired
The filters applied to the query.
Show 3 propertiesHide 3 properties
meterNameslist of stringsRequired
Meter names the results were filtered to.
paymentMethodIdslist of stringsRequired
Payment method IDs the results were filtered to.
projectNameslist of stringsRequired
Project names the results were filtered to.
formatstringRequired
The output format. Either csv or json.
granularitystringRequired
The time bucket used for aggregation.
groupBylist of stringsRequired
The list of fields that the results are grouped by.
recordsintegerRequired
The number of result records returned.
startstringRequiredformat: date
The start date of the query.
valuelist of objectsMeterDataRequired
The usage data per day per meter
Show 16 propertiesHide 16 properties
coststringRequired
Monetary value of usage for this record, in the currency specified by the currency field. How this is charged depends on the entitlement type: for a license entitlement the amount is fully covered and nothing is billed; for cash, quantity, or pre-commitment entitlements this amount is deducted from the entitlement balance; with no entitlement the amount is billed directly.
currencystringRequired
The currency of the cost field.
datestringRequiredformat: date-time
The date and time of this usage record. Truncated to the granularity of the query (e.g. if granularity is 'day' then time will be 00:00:00).
dateProcessedstring or nullOptionalformat: date-time
The report_time truncated to the requested granularity. Null for usage that has not yet been charged. Comparing against date (sample_time) reveals late-reported data.
entitlementstring or nullOptionalformat: uuid
The ID of the entitlement applied to this usage. Can be joined against the /entitlements endpoint.
entitlementTypestring or nullOptional
The type of entitlement applied to this usage, if any.
familystringOptional
Product family this meter belongs to.
meterNamestringRequired
The meter name.
meterSkustring or nullOptional
The SaaS SKU identifier for this meter.
paymentMethodstringOptionalformat: uuid
The ID of the payment method associated with this usage.
paymentMethodNamestring or nullOptional
The display name of the payment method associated with this usage.
pricedoubleOptional
Per-unit price for this record (cost / quantity).
projectstringOptional
The name of the project this usage belongs to.
quantitydoubleRequired
Total units accrued for this record.
solutionstringOptional
Solution within the product family this meter belongs to.
unitstring or nullOptional
The unit that this meter is reported in, e.g. 'gigabytes' or 'minutes'.

Errors

400 Bad Request
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
401 Unauthorized
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
403 Forbidden
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
404 Not Found
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
409 Conflict
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
429 Too Many Requests
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code
500 Internal Server Error
errorobjectErrorDetailRequired
Pertinent information about the error
Show 3 propertiesHide 3 properties
codestringRequired
The error code.
detailstringRequired
The error message.
extraDetailmap from strings to anyOptional
Extra information regarding this error.
Show value schemaHide value schema
[any key]any
refstringRequired
A reference to the request that caused the error.
statusintegerRequired
The HTTP status code