> ## Documentation Index
> Fetch the complete documentation index at: https://docs.subtotal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Usage

> Your plan usage for one window, as Settings · Usage in the dashboard shows it: each metric's count against its included quota and overage fee. Defaults to the current window; `periods` lists every window.

[Subtotal Connector tool: get\_usage](https://docs.subtotal.com/docs/connector/tools.md#get_usage)

Your plan usage for one window, the same figures as **Settings · Usage** in the dashboard: connections, purchases, events, MCP queries and API requests, each counted the way invoicing counts it and shown against your plan's included amount and overage fee. An `included` of `null` means unlimited.

The current window is the default. `periods` lists every window, newest first, including earlier plans'; pass one's `start` as `period_start` to read it, with its `plan_id` if two plans' windows share that start.

Call it with your API key, or with a [Subtotal Connector](https://docs.subtotal.com/docs/connector/introduction.md) OAuth token that includes `usage:read`. A token without it receives `403 insufficient_scope`. [Partner app](https://docs.subtotal.com/docs/partner-apps/introduction.md#fixed-permissions) tokens don't include it.


## OpenAPI

````yaml get /usage
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /usage:
    get:
      tags:
        - usage
      summary: Get Usage
      description: >-
        Your plan usage for one window, as Settings · Usage in the dashboard
        shows it: each metric's count against its included quota and overage
        fee. Defaults to the current window; `periods` lists every window.
      operationId: get_usage_usage_get
      parameters:
        - name: period_start
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: >-
              The `start` of a window from `periods`. Omit for the current
              window.
            title: Period Start
          description: The `start` of a window from `periods`. Omit for the current window.
        - name: plan_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                maxLength: 26
              - type: 'null'
            description: >-
              The window's `plan_id` from `periods`. Needed only when two plans'
              windows share a start.
            title: Plan Id
          description: >-
            The window's `plan_id` from `periods`. Needed only when two plans'
            windows share a start.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '404':
          description: No active plan, or no usage window starts at period_start
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - PartnerOAuth: []
        - ApiKey: []
components:
  schemas:
    UsageResponse:
      properties:
        plan_id:
          type: string
          title: Plan Id
        plan_name:
          type: string
          title: Plan Name
        current_plan:
          type: boolean
          title: Current Plan
          description: False when the window belongs to an earlier plan.
        period_start:
          type: string
          format: date-time
          title: Period Start
        period_end:
          type: string
          format: date-time
          title: Period End
        metrics:
          items:
            $ref: '#/components/schemas/UsageMetric'
          type: array
          title: Metrics
        periods:
          items:
            $ref: '#/components/schemas/UsageWindow'
          type: array
          title: Periods
          description: >-
            Every usage window, newest first: the current plan's, then earlier
            plans'. Pass one's `start` as `period_start` to read it.
      type: object
      required:
        - plan_id
        - plan_name
        - current_plan
        - period_start
        - period_end
        - metrics
        - periods
      title: UsageResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UsageMetric:
      properties:
        metric:
          type: string
          enum:
            - connections
            - purchases
            - events
            - mcp_queries
            - api_requests
          title: Metric
        used:
          type: integer
          title: Used
          description: Counted in this window, the way invoicing counts it.
        included:
          anyOf:
            - type: integer
            - type: 'null'
          title: Included
          description: >-
            Included in the plan for this window. Null means unlimited; 0 with
            no additional_fee means not on the plan.
        additional_fee:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Additional Fee
          description: >-
            Price per unit beyond `included`, in USD. Null means no overage
            billing.
      type: object
      required:
        - metric
        - used
        - included
        - additional_fee
      title: UsageMetric
    UsageWindow:
      properties:
        start:
          type: string
          format: date-time
          title: Start
        end:
          type: string
          format: date-time
          title: End
        plan_id:
          type: string
          title: Plan Id
        plan_name:
          type: string
          title: Plan Name
        current_plan:
          type: boolean
          title: Current Plan
          description: False for a window of an earlier plan.
      type: object
      required:
        - start
        - end
        - plan_id
        - plan_name
        - current_plan
      title: UsageWindow
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    PartnerOAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Partner OAuth: send `Authorization: Bearer <access_token>`, an OAuth
        access token from Subtotal's authorization server with the scope this
        endpoint needs.
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: 'API key: your Subtotal API key.'

````

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