# 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` ## Authentication Authorization Bearer Bearer authentication of the form `Bearer `, where token is your auth token. ## Request 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). | ## Response 200 OK ### Supplemental | 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. | ### Meter Data | 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'. | ## Errors Common errors and their meanings: ### 400 Bad Request Details about the error: - code: string - detail: string - extraDetail: map from strings to any - ref: string - status: integer ### 401 Unauthorized ### 403 Forbidden ### 404 Not Found ### 409 Conflict ### 429 Too Many Requests ### 500 Internal Server Error