> ## Documentation Index > Fetch the complete documentation index at: https://docs.meteroid.com/llms.txt > Use this file to discover all available pages before exploring further. # List a customer's usage costs over time > A customer's usage of one billable metric and what it costs, per hour, day or month, optionally split by an event property, summed across the subscriptions that bill it. Buckets are cut at UTC boundaries and only cover the customer's billing periods. Per-unit and matrix pricing give exact costs. For pricing that depends on the whole period's usage (tiered, volume, package, capacity), a bucket's cost is what it adds to the period's price so far and `exact` is false. The range is at most 93 days. Beta: the request and response shapes of this endpoint may change before general availability. ## OpenAPI ````yaml https://api.meteroid.com/api-docs/openapi.json get /api/v1/usage/customer/{customer_id}/costs openapi: 3.1.0 info: title: meteroid description: '' license: name: LicenseRef-Proprietary identifier: LicenseRef-Proprietary version: 0.1.0 servers: [] security: [] tags: - name: Meteroid description: Meteroid API - name: Add-ons - name: Batch Jobs - name: Budgets description: >- Beta: may change before general availability. Spending limits on a customer's usage, or one subscription's, per currency, with alerts at percentages of the amount. x-beta: true - name: Checkout Sessions - name: Checks description: >- Beta: may change before general availability. Whether a customer may consume more of a feature right now. x-beta: true - name: Connect description: Manage connected accounts (Express & Standard) - name: Coupons - name: Credit Notes - name: Credit units description: >- Custom denominations, such as "credits", that usage can be priced in and credit granted or sold in, instead of money. - name: Credits description: >- Prepaid credit: a customer's wallets, credit grants, ledger and top-ups. Promotional credit applies before tax like a discount; paid credit applies after tax like a payment. - name: Custom Properties - name: Customers - name: Entitlements - name: Events - name: Features - name: Invoices - name: Licenses description: >- Licenses for your customers' self-hosted installations: signed tokens carrying their plan's entitlements, activated and refreshed by the installation over the public licensing endpoints. - name: Metrics - name: OAuth description: OAuth 2.0 token endpoints (public, client-credentials auth) - name: OAuth Apps description: Manage OAuth applications for Connect integrations - name: Plans - name: Product Families - name: Products - name: Subscriptions - name: Usage - name: Usage costs description: >- Beta: may change before general availability. A customer's or a subscription's usage events and usage over time, with what they cost. x-beta: true - name: Webhook Endpoints description: Manage outbound webhook endpoints and inspect their deliveries paths: /api/v1/usage/customer/{customer_id}/costs: get: tags: - Usage costs summary: List a customer's usage costs over time description: >- A customer's usage of one billable metric and what it costs, per hour, day or month, optionally split by an event property, summed across the subscriptions that bill it. Buckets are cut at UTC boundaries and only cover the customer's billing periods. Per-unit and matrix pricing give exact costs. For pricing that depends on the whole period's usage (tiered, volume, package, capacity), a bucket's cost is what it adds to the period's price so far and `exact` is false. The range is at most 93 days. Beta: the request and response shapes of this endpoint may change before general availability. operationId: list_customer_usage_costs parameters: - name: customer_id in: path description: Customer ID or alias required: true schema: type: string - name: metric in: query description: Billable metric, by ID or code. required: true schema: type: string - name: group_by in: query description: Event property to split the usage by. required: false schema: type: string - name: granularity in: query required: true schema: type: string enum: - HOUR - DAY - MONTH - name: from in: query description: Start of the range, inclusive. required: true schema: type: string format: date-time - name: to in: query description: End of the range, exclusive. At most 93 days after `from`. required: true schema: type: string format: date-time responses: '200': description: Usage and cost per bucket content: application/json: schema: $ref: '#/components/schemas/UsageCostListResponse' '400': description: Invalid request or range content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '404': description: Customer or billable metric not found content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '429': description: Too many usage cost reads content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' security: - bearer_auth: [] components: schemas: UsageCostListResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UsageCostRow' RestErrorResponse: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string UsageCostRow: type: object required: - bucket_start - quantity - exact properties: bucket_start: type: string format: date-time cost: oneOf: - $ref: '#/components/schemas/UsageCost' description: >- Rounded to the currency's minor unit so that the rows of a billing period add up to the invoiced amount. Absent when the metric's aggregation cannot be priced per bucket. - type: 'null' exact: type: boolean description: >- False when the price depends on the whole period's usage (tiered, volume, package, capacity): the cost is then what the bucket adds to the period's price so far. A period's rows still add up to its invoiced amount. group: type: - string - 'null' description: >- The value of `group_by` for the row. Absent when the request is not grouped, or the usage has no value for the property. quantity: type: string format: decimal ErrorCode: type: string enum: - BAD_REQUEST - NOT_FOUND - CONFLICT - FORBIDDEN - UNAUTHORIZED - TOKEN_EXPIRED - TOO_MANY_REQUESTS - INTERNAL_SERVER_ERROR UsageCost: type: object description: >- Usage priced as its invoice line prices it, before discounts and credits: tax-inclusive when the subscription's prices are. required: - amount - currency - unit properties: amount: type: string format: decimal currency: type: string description: A currency code, or a credit unit code when `unit` is `CREDIT_UNIT`. unit: $ref: '#/components/schemas/UsageCostUnit' UsageCostUnit: type: string description: What a cost is counted in. enum: - CURRENCY - CREDIT_UNIT securitySchemes: bearer_auth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.