> ## 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 events with their cost > A customer's events for one billable metric, oldest first, each with the units it adds and what they cost at the price in force. The cost is exact for per-unit and matrix pricing and absent for pricing that depends on the whole period's usage (tiered, volume, package, capacity) and for aggregations that cannot be split per event. 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}/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/customer/{customer_id}/events: get: tags: - Usage costs summary: List a customer's usage events with their cost description: >- A customer's events for one billable metric, oldest first, each with the units it adds and what they cost at the price in force. The cost is exact for per-unit and matrix pricing and absent for pricing that depends on the whole period's usage (tiered, volume, package, capacity) and for aggregations that cannot be split per event. 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_events 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: 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 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: 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.