Get usage report – Management API – MediaKind

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 includes 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

Authorization Bearer

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

This endpoint expects an object.

Parameter	Type	Required	Description
download	boolean	Optional	Defaults to false. When true, sets response headers to prompt a browser file download.
endDate	string	Required	End date of the usage report (exclusive). 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'.
filterOnReportedDate	boolean	Optional	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.
format	enum	Optional	Response format. Either 'json' or 'csv'. Defaults to 'json'. Allowed values: json, csv
granularity	enum	Optional	Time bucket for aggregation. Defaults to 'day'. Allowed values: year, month, week, day, hour
groupBy	list of strings	Optional	Fields to group results by. Only 'meter' is currently valid. Defaults to ['meter'].
meterNames	list of strings	Optional	Filter results to the specified meter names.
paymentMethodIds	list of strings	Optional	Filter results to the specified payment method IDs. Mutually exclusive with projectNames.
projectNames	list of strings	Optional	Filter results to the specified project names. Mutually exclusive with paymentMethodIds.
startDate	string	Required	Start date of the usage report (inclusive).

200 OK

Parameter	Type	Required	Description
download	boolean	Required	Whether browser was indicated to download file
end	string	Required	The end date of the query.
filters	object	Required	The filters applied to the query.
meterNames	list of strings	Required	Meter names the results were filtered to.
paymentMethodIds	list of strings	Required	Payment method IDs the results were filtered to.
projectNames	list of strings	Required	Project names the results were filtered to.
format	string	Required	The output format. Either csv or json.
granularity	string	Required	The time bucket used for aggregation.
groupBy	list of strings	Required	The list of fields that the results are grouped by.
records	integer	Required	The number of result records returned.
start	string	Required	The start date of the query.

Parameter	Type	Required	Description
cost	string	Required	Monetary value of usage for this record, in the currency specified by the currency field.
currency	string	Required	The currency of the cost field.
date	string	Required	The date and time of this usage record.
dateProcessed	string or null	Optional	The report_time truncated to the requested granularity.
entitlement	string or null	Optional	The ID of the entitlement applied to this usage.
entitlementType	string or null	Optional	The type of entitlement applied to this usage, if any.
family	string	Optional	Product family this meter belongs to.
meterName	string	Required	The meter name.
meterSku	string or null	Optional	The SaaS SKU identifier for this meter.
paymentMethod	string	Optional	The ID of the payment method associated with this usage.
paymentMethodName	string or null	Optional	The display name of the payment method associated with this usage.
price	double	Optional	Per-unit price for this record (cost / quantity).
project	string	Optional	The name of the project this usage belongs to.
quantity	double	Required	Total units accrued for this record.
solution	string	Optional	Solution within the product family this meter belongs to.
unit	string or null	Optional	The unit that this meter is reported in, e.g., 'gigabytes' or 'minutes'.

Common errors and their meanings:

Details about the error: