> ## 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 subscription's usage costs over time > The subscription's usage of one billable metric and what it costs, as for a customer but counting only the events the subscription bills (see its usage filter) and only its own billing periods. 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/subscription/{subscription_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/subscription/{subscription_id}/costs: get: tags: - Usage costs summary: List a subscription's usage costs over time description: >- The subscription's usage of one billable metric and what it costs, as for a customer but counting only the events the subscription bills (see its usage filter) and only its own billing periods. The range is at most 93 days. Beta: the request and response shapes of this endpoint may change before general availability. operationId: list_subscription_usage_costs parameters: - name: subscription_id in: path description: Subscription ID required: true schema: $ref: '#/components/schemas/SubscriptionId' - 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, or a metric the subscription does not bill content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '404': description: Subscription 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: SubscriptionId: type: string format: MeteroidId examples: - sub_7n42DGM5Tflk9n8mt7Fhc7 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.