> ## 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 events with their cost > The events of one billable metric that the subscription bills, oldest first: with a usage filter, only the customer's events matching it; without, those no other subscription's filter claims. Costs are as for the customer's events. 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}/events 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}/events: get: tags: - Usage costs summary: List a subscription's usage events with their cost description: >- The events of one billable metric that the subscription bills, oldest first: with a usage filter, only the customer's events matching it; without, those no other subscription's filter claims. Costs are as for the customer's events. 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_events 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: 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 - name: cursor in: query description: The `next_cursor` of the previous page. required: false schema: type: string - name: limit in: query description: Page size, 100 by default and 500 at most. required: false schema: type: integer format: int32 minimum: 0 responses: '200': description: A page of events content: application/json: schema: $ref: '#/components/schemas/UsageEventListResponse' '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 UsageEventListResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/UsageEvent' next_cursor: type: - string - 'null' description: Absent on the last page. RestErrorResponse: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string UsageEvent: type: object required: - id - timestamp - properties properties: cost: oneOf: - $ref: '#/components/schemas/UsageCost' description: >- The event's cost at the price in force, unrounded. Present for per-unit and matrix pricing only: absent for tiered, volume, package and capacity pricing, whose price depends on the whole period's usage, and for a metric whose unit conversion rounds. - type: 'null' id: type: string properties: type: object additionalProperties: type: string propertyNames: type: string quantity: type: - string - 'null' format: decimal description: >- Billed units the event adds. Absent when the metric's aggregation cannot be split per event, or when the event does not count towards the metric. timestamp: type: string format: date-time 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.