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

# Get subscription usage

> Unmetered allowance report shared by all credentials on this subscription.

Examples use fictional test data and illustrative IDs, dates, and allowances. They are not live prospects or current account balances.



## OpenAPI

````yaml /openapi.json get /api/usage
openapi: 3.1.0
info:
  title: Jolts API
  version: 1.0.0
  description: >-
    Implemented HTTP contract. Authentication uses an account-scoped bearer
    credential. Current coverage is partial; a matching company is not a
    guarantee of buying intent.


    Response examples use fictional test companies and illustrative IDs, dates
    and allowances. They are not live customer results or evidence of market
    coverage.
servers:
  - url: https://app.jolts.xyz
    description: Application API
security:
  - bearerAuth: []
tags:
  - name: Companies
    description: Find prospects and investigate their supporting evidence.
  - name: Observations
    description: Search individual company activities and inspect their sources.
  - name: Operations
    description: Start background work and retrieve its results.
  - name: Account
    description: Check your subscription and shared usage allowance.
paths:
  /api/usage:
    get:
      tags:
        - Account
      summary: Get subscription usage
      description: >-
        Unmetered allowance report shared by all credentials on this
        subscription.


        Examples use fictional test data and illustrative IDs, dates, and
        allowances. They are not live prospects or current account balances.
      operationId: getUsageReport
      responses:
        '200':
          description: Current subscription usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageReport'
              examples:
                result:
                  $ref: '#/components/examples/getUsageReport200'
        '401':
          description: Missing or revoked API credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/invalidCredential'
        '402':
          description: An active or trialing subscription is required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                error:
                  $ref: '#/components/examples/subscriptionRequired'
components:
  schemas:
    UsageReport:
      type: object
      properties:
        subscription:
          type: object
          properties:
            plan:
              type: string
            status:
              type: string
            current_period_start:
              type:
                - string
                - 'null'
              format: date-time
            current_period_end:
              type:
                - string
                - 'null'
              format: date-time
          required:
            - plan
            - status
            - current_period_start
            - current_period_end
          additionalProperties: false
        usage:
          type: object
          properties:
            request_units:
              type: integer
              minimum: 0
            weekly_request_units:
              type: integer
              minimum: 0
            delivered_units:
              type: integer
              minimum: 0
            weekly_delivered_units:
              type: integer
              minimum: 0
            fresh_evidence_units:
              type: integer
              minimum: 0
          required:
            - request_units
            - weekly_request_units
            - delivered_units
            - weekly_delivered_units
            - fresh_evidence_units
          additionalProperties: false
        limits:
          type: object
          properties:
            request_units:
              type: integer
              minimum: 0
            weekly_request_units:
              type: integer
              minimum: 0
            delivered_units:
              type: integer
              minimum: 0
            weekly_delivered_units:
              type: integer
              minimum: 0
          required:
            - request_units
            - weekly_request_units
            - delivered_units
            - weekly_delivered_units
          additionalProperties: false
        reservations:
          type: object
          properties:
            request_units:
              type: integer
              minimum: 0
            delivered_units:
              type: integer
              minimum: 0
          required:
            - request_units
            - delivered_units
          additionalProperties: false
      required:
        - subscription
        - usage
        - limits
        - reservations
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retry_at:
              type: string
              format: date-time
              description: >-
                Advisory retry time for the reached capacity limit, based on
                usage at rejection. Other requests or completing reservations
                may change availability.
            retry_after_seconds:
              type: integer
              minimum: 0
              description: >-
                Seconds from rejection to retry_at. For stored failed
                operations, prefer the absolute retry_at timestamp.
          required:
            - code
            - message
          additionalProperties: false
        usage:
          $ref: '#/components/schemas/Operation'
        request_allowance:
          $ref: '#/components/schemas/Allowance'
      required:
        - error
      additionalProperties: false
    Operation:
      type: object
      properties:
        id:
          type: integer
          minimum: 1
        status:
          type: string
          enum:
            - pending
            - processing
            - delivered
            - failed
        request_key:
          type: string
        request_units:
          type: integer
          minimum: 0
        delivered_units:
          type: integer
          minimum: 0
        fresh_evidence_units:
          type: integer
          minimum: 0
      required:
        - id
        - status
        - request_key
        - request_units
        - delivered_units
        - fresh_evidence_units
      additionalProperties: false
    Allowance:
      type: object
      properties:
        window_seconds:
          type: integer
          minimum: 0
        window_remaining:
          type: integer
          minimum: 0
        weekly_remaining:
          type: integer
          minimum: 0
      required:
        - window_seconds
        - window_remaining
        - weekly_remaining
      additionalProperties: false
  examples:
    getUsageReport200:
      summary: Illustrative result (fictional test data)
      value:
        subscription:
          plan: builder
          status: active
          current_period_start: '2026-09-18T02:47:05Z'
          current_period_end: '2026-10-16T02:47:05Z'
        usage:
          request_units: 3
          weekly_request_units: 3
          delivered_units: 4
          weekly_delivered_units: 4
          fresh_evidence_units: 0
        limits:
          request_units: 200
          weekly_request_units: 1000
          delivered_units: 500
          weekly_delivered_units: 2500
        reservations:
          request_units: 1
          delivered_units: 10
    invalidCredential:
      summary: invalid_api_key
      value:
        error:
          code: invalid_api_key
          message: Provide a valid API credential.
    subscriptionRequired:
      summary: subscription_required
      value:
        error:
          code: subscription_required
          message: An active or trialing subscription is required.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````