> ## 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.

# Get subscription usage

> Retrieve aggregated usage data for a subscription's usage-based components.
If start_date/end_date are omitted, defaults to the current billing period, and the response
then carries the running total (beta): what each metric's usage adds so far to the next invoice,
and what they add up to, before discounts and credits. That reading is shared for up to 30
seconds (see `computed_at`). Counts towards the usage cost reads' rate limit.



## OpenAPI

````yaml https://api.meteroid.com/api-docs/openapi.json get /api/v1/usage/subscription/{subscription_id}
openapi: 3.1.0
info:
  title: meteroid
  description: ''
  license:
    name: LicenseRef-Meteroid-EE
    identifier: LicenseRef-Meteroid-EE
  version: 0.1.0
servers: []
security: []
tags:
  - 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}:
    get:
      tags:
        - Usage
      summary: Get subscription usage
      description: >-
        Retrieve aggregated usage data for a subscription's usage-based
        components.

        If start_date/end_date are omitted, defaults to the current billing
        period, and the response

        then carries the running total (beta): what each metric's usage adds so
        far to the next invoice,

        and what they add up to, before discounts and credits. That reading is
        shared for up to 30

        seconds (see `computed_at`). Counts towards the usage cost reads' rate
        limit.
      operationId: get_subscription_usage
      parameters:
        - name: subscription_id
          in: path
          description: Subscription ID
          required: true
          schema:
            $ref: '#/components/schemas/SubscriptionId'
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
        - name: metric_id
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/BillableMetricId'
      responses:
        '200':
          description: Subscription usage data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestErrorResponse'
        '404':
          description: Subscription 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
    BillableMetricId:
      type: string
      format: MeteroidId
      examples:
        - bm_7n42DGM5Tflk9n8mt7Fhc7
    UsageResponse:
      type: object
      required:
        - period_start
        - period_end
        - usage
      properties:
        computed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Beta: when `totals` and the metrics' `costs` were computed. These
            are present only when a

            subscription's current billing period is read (no `start_date` nor
            `end_date`) and its

            usage could be priced.
        period_end:
          type: string
          format: date
        period_start:
          type: string
          format: date
        totals:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/UsageCost'
          description: 'Beta: the sum of the metrics'' `costs`, per currency or credit unit.'
        usage:
          type: array
          items:
            $ref: '#/components/schemas/MetricUsage'
    RestErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
    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'
    MetricUsage:
      type: object
      required:
        - metric_id
        - metric_name
        - metric_code
        - total_value
        - grouped_usage
      properties:
        costs:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/UsageCost'
          description: >-
            Beta: what the metric's usage adds so far to the subscription's next
            invoice, per currency

            or credit unit; empty while it bills nothing, as during a free trial
            or once cancelled.
        grouped_usage:
          type: array
          items:
            $ref: '#/components/schemas/GroupedUsage'
        metric_code:
          type: string
        metric_id:
          $ref: '#/components/schemas/BillableMetricId'
        metric_name:
          type: string
        total_value:
          type: string
          format: decimal
    ErrorCode:
      type: string
      enum:
        - BAD_REQUEST
        - NOT_FOUND
        - CONFLICT
        - FORBIDDEN
        - UNAUTHORIZED
        - TOKEN_EXPIRED
        - TOO_MANY_REQUESTS
        - INTERNAL_SERVER_ERROR
    UsageCostUnit:
      type: string
      description: What a cost is counted in.
      enum:
        - CURRENCY
        - CREDIT_UNIT
    GroupedUsage:
      type: object
      required:
        - value
        - dimensions
      properties:
        dimensions:
          type: object
          additionalProperties:
            type: string
          propertyNames:
            type: string
        value:
          type: string
          format: decimal
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.