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

# Usage pool balance and metered activity



## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/usage
openapi: 3.1.0
info:
  title: Cactus Partner API
  version: 1.0.0-draft.1
  summary: Document extraction and automated underwriting for CRE.
  description: |
    # Overview

    The Cactus Partner API provides two products:

    - **Extraction** — upload commercial real estate documents (offering
      memoranda, rent rolls, T-12 / operating statements, and other business
      documents) and receive structured, validated JSON with per-field
      confidence.
    - **Underwriting** — provide a property address, asset class, and
      notification email (documents optional) to run a full automated
      underwriting; results are delivered as a hosted financial-analysis
      report link plus a machine-readable summary.

    ## Authentication

    Every request carries an API key:
    `Authorization: Bearer ck_live_...` (or `ck_sandbox_...`).
    Keys are issued by Cactus at kickoff, are scoped per product, and can be
    rotated or revoked at any time.

    ## Sandbox

    `ck_sandbox_` keys hit the same endpoints but never debit your usage
    pool: uploads are accepted, and jobs return deterministic fixture output
    within seconds. Use sandbox keys for integration development and CI.

    ## Asynchronous jobs

    Extractions and underwritings are asynchronous. Create the job (`202
    Accepted`), then either poll the job resource or register a webhook
    endpoint to receive signed events (recommended). Typical extraction
    turnaround is minutes.

    ## Billing semantics

    A document is **accepted** when it passes validation (size caps, page/row
    counts, type resolution). Acceptance debits your usage pool at the fixed
    rate-card price for the document type — before processing, so pricing is
    deterministic. Rejected documents are never charged. Documents exceeding
    their type's size cap bill as multiple units of the same type; the accept
    response discloses `billed.units`. Files over 500 pages or 100 MB are
    rejected outright.

    ## Idempotency

    All `POST` endpoints accept an `Idempotency-Key` header (any unique
    string, e.g. a UUID). Retrying a request with the same key returns the
    original response instead of creating a duplicate.

    ## Errors

    Errors follow RFC 9457 (`application/problem+json`) and always include a
    stable machine-readable `code` and the `request_id` to quote in support
    requests.

    ## Versioning

    The path major version (`/v1`) changes only for breaking API changes.
    Extraction output schemas are versioned independently per document type
    (e.g. `rent_roll.v1`) and declared in every result; breaking output
    changes ship as a new schema version with advance notice and an overlap
    window.

    ---
    All field-level output schemas — `RentRollData` (`rent_roll.v1`),
    `T12Data` (`t12.v1`), `OfferingMemorandumData`
    (`offering_memorandum.v1`), and `GenericDocumentData` (`facts.v1`) —
    are finalized against the extraction engine's real output.
  contact:
    name: Cactus API Support
    email: api@trycactus.com
  license:
    name: Proprietary — Cactus API License Agreement
    identifier: LicenseRef-Cactus-Partner-Agreement
servers:
  - url: https://api.trycactus.com
    description: Production (live and sandbox keys)
security:
  - apiKey: []
tags:
  - name: Documents
    description: Upload and manage documents via presigned URLs.
  - name: Extractions
    description: Structured data extraction jobs and results.
  - name: Underwritings
    description: Automated underwriting runs.
  - name: Usage
    description: Usage pool balance and metered activity.
  - name: Webhook Endpoints
    description: Manage endpoints that receive signed event notifications.
paths:
  /v1/usage:
    get:
      tags:
        - Usage
      summary: Usage pool balance and metered activity
      operationId: getUsage
      parameters:
        - name: period_start
          in: query
          schema:
            type: string
            format: date
          description: Defaults to the first day of the current month.
        - name: period_end
          in: query
          schema:
            type: string
            format: date
          description: Defaults to today.
      responses:
        '200':
          description: Balance and per-rate-code usage for the period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
components:
  schemas:
    Usage:
      type: object
      required:
        - pool
        - period
      properties:
        pool:
          type: object
          required:
            - balance_usd
          properties:
            balance_usd:
              type: string
              description: Current usage-pool balance. Negative while in arrears (overage).
              example: '1437.00'
        period:
          type: object
          required:
            - start
            - end
            - total_usd
          properties:
            start:
              type: string
              format: date
            end:
              type: string
              format: date
            total_usd:
              type: string
              example: '1063.00'
            line_items:
              type: array
              items:
                type: object
                required:
                  - rate_code
                  - count
                  - units
                  - amount_usd
                properties:
                  rate_code:
                    type: string
                    example: rent_roll
                  count:
                    type: integer
                    description: Number of accepted documents.
                  units:
                    type: integer
                    description: Billing units (>= count when size caps multiply).
                  amount_usd:
                    type: string
        overage_usd:
          type: string
          description: Period spend beyond the prepaid pool (invoiced in arrears).
          example: '0.00'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: ck_live_* or ck_sandbox_*
      description: Partner API key issued by Cactus.

````