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

# Get usage

> Read today's organization usage with an inference key



## OpenAPI

````yaml api-reference/platform.json GET /api/v1/usage
openapi: 3.1.0
info:
  title: Subconscious platform API
  version: 1.0.0
  description: >-
    Inference-key management, priced model discovery, and organization usage on
    the Subconscious platform. Inference stays on
    https://api.subconscious.dev/v1.
servers:
  - url: https://platform.subconscious.dev
security: []
paths:
  /api/v1/usage:
    get:
      summary: Get usage
      description: >-
        Today's usage for the organization that owns the inference key: billing
        terms, plan, credit balance, the active invoice window for invoiced
        organizations, and tokens consumed today by model. The response has two
        shapes. A prepaid organization spends a wallet and plan allowance, so it
        reports `credits` with a daily allowance percentage, and `invoice` is
        null. An invoiced organization bills a monthly net-30 invoice against a
        spend limit, so it reports `invoice` with the period window, accrued
        spend at its rates, and its spend limit, and `credits` and the daily
        allowance are null. Authenticate with an inference key (`Authorization:
        Bearer` or `X-API-Key`). Management keys are rejected. The allowance is
        a percentage of today's grant. The grant amount itself is not included.
      operationId: getUsage
      responses:
        '200':
          description: >-
            Organization usage snapshot. Prepaid organizations carry `credits`
            and a daily allowance; invoiced organizations carry the `invoice`
            window instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
              examples:
                prepaid:
                  summary: Prepaid organization
                  value:
                    billingTerms: prepaid
                    plan:
                      label: Heavy
                      status: active
                      dailyAllowance:
                        basis: credit
                        percent: 5.5
                        resetAt: '2026-09-24T00:00:00.000Z'
                    credits:
                      balanceDollars: 12.34
                      overageThisPeriodDollars: 0
                    invoice: null
                    models:
                      - slug: subconscious/glm-5.3-marathon
                        consumedToday: 44500000
                invoiced:
                  summary: Invoiced organization
                  value:
                    billingTerms: invoiced
                    plan:
                      label: null
                      status: null
                      dailyAllowance: null
                    credits: null
                    invoice:
                      accruedThisPeriodDollars: 1234.56
                      periodStart: '2026-10-01T00:00:00.000Z'
                      periodEnd: '2026-11-01T00:00:00.000Z'
                      limitDollars: 5000
                    models:
                      - slug: subconscious/glm-5.3-marathon
                        consumedToday: 44500000
        '401':
          description: Missing, inactive, or non-inference API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The organization does not have closed-beta access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Closed-beta access is required
        '502':
          description: Usage could not be read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
        - apiKeyAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl https://platform.subconscious.dev/api/v1/usage \
              -H "Authorization: Bearer sk-gw-..."
components:
  schemas:
    Usage:
      type: object
      required:
        - billingTerms
        - plan
        - credits
        - invoice
        - models
      properties:
        billingTerms:
          type: string
          enum:
            - prepaid
            - invoiced
          description: >-
            How the organization is billed. `prepaid` spends a wallet and plan
            allowance; `invoiced` bills a monthly net-30 invoice against a spend
            limit.
        plan:
          type: object
          required:
            - label
            - status
            - dailyAllowance
          properties:
            label:
              type:
                - string
                - 'null'
              description: Plan name. Null when the organization has no plan.
            status:
              type:
                - string
                - 'null'
              description: Plan status, such as `active`.
            dailyAllowance:
              description: >-
                Share of today's allowance. Prepaid organizations only. Null for
                invoiced organizations, which bill against a spend limit rather
                than a daily grant, and for organizations with no allowance.
                `percent` can exceed 100 when usage is past the allowance.
                `basis` is `credit` when the day is sized in credits, `tokens`
                when it is sized in tokens, and `unavailable` when a
                credit-billed read failed.
              oneOf:
                - $ref: '#/components/schemas/CreditOrTokenAllowance'
                - $ref: '#/components/schemas/UnavailableAllowance'
                - type: 'null'
        credits:
          description: >-
            Wallet balance and overage. Null for invoiced organizations, which
            have no wallet.
          oneOf:
            - $ref: '#/components/schemas/Credits'
            - type: 'null'
        invoice:
          description: The active invoice window. Null for prepaid organizations.
          oneOf:
            - $ref: '#/components/schemas/InvoiceUsage'
            - type: 'null'
        models:
          type: array
          description: >-
            Models with usage today. A model with no usage today is omitted,
            which means zero tokens so far.
          items:
            type: object
            required:
              - slug
              - consumedToday
            properties:
              slug:
                type: string
                example: subconscious/glm-5.3-marathon
              consumedToday:
                type: integer
                description: Tokens consumed by this model since UTC midnight.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    CreditOrTokenAllowance:
      type: object
      required:
        - basis
        - percent
        - resetAt
      properties:
        basis:
          type: string
          enum:
            - credit
            - tokens
        percent:
          type: number
          description: Percent of today's allowance already used. Can exceed 100.
        resetAt:
          type: string
          format: date-time
          description: When the daily counter resets (UTC midnight).
    UnavailableAllowance:
      type: object
      required:
        - basis
        - resetAt
      properties:
        basis:
          type: string
          enum:
            - unavailable
        resetAt:
          type: string
          format: date-time
    Credits:
      type: object
      required:
        - balanceDollars
        - overageThisPeriodDollars
      properties:
        balanceDollars:
          type:
            - number
            - 'null'
          description: >-
            Spendable credit balance in dollars. Null when the balance cannot be
            read.
        overageThisPeriodDollars:
          type: number
          description: Overage for the current period, in dollars. Currently always 0.
    InvoiceUsage:
      type: object
      required:
        - accruedThisPeriodDollars
        - periodStart
        - periodEnd
        - limitDollars
      properties:
        accruedThisPeriodDollars:
          type:
            - number
            - 'null'
          description: >-
            Usage so far this period at the organization's rates, in dollars.
            Null when the read failed; never shown as zero.
        periodStart:
          type: string
          format: date-time
          description: >-
            Start of the current invoice period. Empty when the accrued read
            failed.
        periodEnd:
          type: string
          format: date-time
          description: End of the current invoice period. The spend limit resets here.
        limitDollars:
          type:
            - number
            - 'null'
          description: >-
            The spend limit in dollars. Null when the organization has none
            enabled.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key in the Authorization header. Management endpoints require a
        management key (`sk-mgmt-...`). GET /api/v1/models and GET /api/v1/usage
        require an inference key (`sk-gw-...`).
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Same key as bearer auth, passed in the X-API-Key header.

````

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