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

# Page exact model-cost attempts and charges for a session scope



## OpenAPI

````yaml /managed-agents/openapi.yaml get /managed-agents/v1/sessions/{session_id}/costs
openapi: 3.1.0
info:
  title: Managed Agents API
  version: 0.13.0
  description: >-
    The Recursion Managed Agents REST API. Authenticate with a Recursion API key
    as a bearer token. An organization-scoped key acts in its own organization
    and needs nothing else; a tenant-scoped key must also send
    `x-organization-id` with an organization id or `default`. Field names follow
    each operation's published schema.
servers:
  - url: https://api.recursion.labelbox.com
security:
  - bearerAuth: []
paths:
  /managed-agents/v1/sessions/{session_id}/costs:
    get:
      tags:
        - Session Model Costs
      summary: Page exact model-cost attempts and charges for a session scope
      operationId: managedAgentsGetSessionModelCosts
      parameters:
        - description: >-
            self selects only this session; subtree selects this session and
            descendants; tree selects the complete root tree.
          in: query
          name: scope
          schema:
            default: self
            description: >-
              self selects only this session; subtree selects this session and
              descendants; tree selects the complete root tree.
            enum:
              - self
              - subtree
              - tree
            type: string
        - in: query
          name: limit
          schema:
            default: 50
            maximum: 100
            minimum: 1
            type: integer
        - description: >-
            Signed, organization/session/scope/limit/snapshot-bound continuation
            token.
          in: query
          name: page_token
          schema:
            description: >-
              Signed, organization/session/scope/limit/snapshot-bound
              continuation token.
            type: string
        - description: >-
            Signed token returned by a model-cost detail page. Pins this
            companion read to the exact same organization/session/scope
            snapshot.
          in: query
          name: model_cost_snapshot_token
          schema:
            description: >-
              Signed token returned by a model-cost detail page. Pins this
              companion read to the exact same organization/session/scope
              snapshot.
            type: string
        - description: >-
            Session id (UUID) the cost read is scoped to. Any id in the tree;
            scope decides how far the read reaches from it. An id outside the
            caller's organization/access policy returns a non-disclosing 404.
          in: path
          name: session_id
          required: true
          schema:
            description: >-
              Session id (UUID) the cost read is scoped to. Any id in the tree;
              scope decides how far the read reaches from it. An id outside the
              caller's organization/access policy returns a non-disclosing 404.
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ManagedAgentsSessionModelCostDetailResponse
          description: >-
            One page of model-cost attempts for a session scope, together with
            the rollups for the same pinned snapshot, so a page and its totals
            cannot disagree. Continuation pages and companion hierarchy reads
            stay on that snapshot rather than re-reading a moving ledger.
        '400':
          description: The request was rejected by schema or semantic validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiError'
        '401':
          description: The caller is unauthenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiError'
        '403':
          description: The caller lacks a required permission or capability.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden'
        '404':
          description: No such resource is reachable for this caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiError'
        '429':
          headers:
            Retry-After:
              description: Seconds the caller should wait before retrying.
              schema:
                type: string
              style: simple
          description: A rate limit is exhausted. Honor `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiError'
        '500':
          description: An unexpected server-side failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiError'
        '502':
          description: The service returned an invalid response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorBadGateway'
        '503':
          headers:
            Retry-After:
              description: Seconds the caller should wait before retrying.
              schema:
                type: string
              style: simple
          description: A dependency is unavailable. Retryable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiError'
        '504':
          headers:
            Retry-After:
              description: When to retry, as delay seconds or an HTTP date.
              schema:
                type: string
          description: The service did not respond before the timeout. Retryable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorGatewayTimeout'
components:
  schemas:
    ManagedAgentsSessionModelCostDetailResponse:
      description: >-
        One page of model-cost attempts for a session scope, together with the
        rollups for the same pinned snapshot, so a page and its totals cannot
        disagree. Continuation pages and companion hierarchy reads stay on that
        snapshot rather than re-reading a moving ledger.
      properties:
        attempts:
          description: >-
            Attempts in scope, oldest first by reservation time, up to the
            requested limit.
          items:
            $ref: '#/components/schemas/ManagedAgentsModelCostAttemptResponse'
          type: array
        model_cost_snapshot_token:
          description: >-
            Signed organization/session/scope-bound token that pins companion
            model-cost reads to this exact snapshot.
          type: string
        next_page_token:
          description: >-
            Continuation for the next page, passed back as page_token. Absent on
            the last page. It is bound to this organization, session, scope,
            limit, and snapshot, so it cannot be replayed against a different
            read.
          type: string
        read_timestamp:
          description: >-
            RFC 3339 timestamp of the database snapshot every figure on this
            page was read from.
          format: date-time
          type: string
        scope:
          description: >-
            How far the read reached from that session: this session alone
            (self), this session and its descendants (subtree), or every session
            under the same root (tree).
          enum:
            - self
            - subtree
            - tree
          type: string
        session_id:
          description: Session the read was scoped to (UUID).
          type: string
        summaries:
          $ref: '#/components/schemas/ManagedAgentsSessionModelCostSummariesResponse'
          description: >-
            Self, subtree, and tree totals from the same pinned snapshot as this
            attempt page.
        summary:
          $ref: '#/components/schemas/ManagedAgentsSessionModelCostSummaryResponse'
          description: >-
            Rollup for the requested scope, from the same pinned snapshot as
            this attempt page.
      required:
        - session_id
        - scope
        - summary
        - summaries
        - attempts
        - model_cost_snapshot_token
        - read_timestamp
      type: object
      example:
        attempts:
          - attempt_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            catalog_version: example
            charge:
              adjustments:
                - adjustment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
                  created_at: '2026-02-18T09:30:00.000Z'
                  created_by: example
                  kind: provider_authority
                  model_cost_usd: example
                  reason: example
              charge_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
              completeness: complete
              components:
                - cache_state: none
                  category: input
                  component_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
                  dimension: example
                  modality: text
                  model_cost_usd: example
                  price:
                    catalog_version: example
                    currency: USD
                    denominator_units: example
                    model: example
                    numerator_nano_usd: example
                    provider: example
                    region: example
                    rule_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
                    service_tier: example
                  price_redacted: true
                  quantity: example
                  unit: token
              locally_priced_model_cost_usd: example
              model_cost_usd: example
              original_model_cost_usd: example
              provider_reported_model_cost_usd: example
              receipt:
                provider_request_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
                quantities:
                  - cache_state: none
                    category: input
                    dimension: example
                    modality: text
                    quantity: example
                    unit: token
                recovery:
                  method: example
                  recovered_at: '2026-02-18T09:30:00.000Z'
                  reference: example
                redacted_fields:
                  - example
                region: example
                requested_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
                resolved_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
                service_tier: example
                source: example
              receipt_sha256: example
              recorded_at: '2026-02-18T09:30:00.000Z'
            completeness: complete
            created_at: '2026-02-18T09:30:00.000Z'
            kind: model
            model: example
            model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            parent_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            provider: example
            root_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            session_path: example
            state: prepared
            thread_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            updated_at: '2026-02-18T09:30:00.000Z'
        model_cost_snapshot_token: example
        next_page_token: example
        read_timestamp: '2026-02-18T09:30:00.000Z'
        scope: self
        session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        summaries:
          self:
            adjustment_count: example
            attempt_count: example
            charge_count: example
            completeness: complete
            model_cost_usd: example
            scope: self
            session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
          session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
          subtree:
            adjustment_count: example
            attempt_count: example
            charge_count: example
            completeness: complete
            model_cost_usd: example
            scope: self
            session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
          tree:
            adjustment_count: example
            attempt_count: example
            charge_count: example
            completeness: complete
            model_cost_usd: example
            scope: self
            session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        summary:
          adjustment_count: example
          attempt_count: example
          charge_count: example
          completeness: complete
          model_cost_usd: example
          scope: self
          session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
    ManagedAgentsApiError:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - analytics
            - analytics_not_ready
            - artifact_fetch_unavailable
            - artifact_generation_mismatch
            - artifact_hash_mismatch
            - artifact_invalid_events
            - artifact_invalid_json
            - artifact_not_allowlisted
            - artifact_size_mismatch
            - atlassian_rate_limited
            - atlassian_unavailable
            - atomic_ingest_timeout
            - auth_unavailable
            - automation_event_source_invalid
            - automation_memory_unavailable
            - automation_reference_invalid
            - automation_runs_unconfigured
            - automations_unconfigured
            - bad_gateway
            - built_in_catalog_unavailable
            - built_in_integrations_disabled
            - built_in_integrations_unconfigured
            - compute_offerings_unavailable
            - conflict
            - content_store_request_canceled
            - content_store_unavailable
            - content_store_upload_timeout
            - credential_encryption_unconfigured
            - delegate_preparation_failed
            - entity_family_not_permitted
            - environment_not_verified
            - evaluation_cancellation_pending
            - evaluation_deletion_pending
            - event_admission_unavailable
            - event_ingress_unavailable
            - event_source_verification_credential_invalid
            - event_sources_unconfigured
            - execution_unconfigured
            - file_quota_exceeded
            - file_storage_unconfigured
            - forbidden
            - gateway_timeout
            - gestalt_unconfigured
            - github_rate_limited
            - github_unavailable
            - handoff_access_invalid
            - handoff_access_unavailable
            - handoff_access_unsupported
            - handoff_capture_unavailable
            - handoff_requires_retest
            - handoff_revoke_unavailable
            - handoff_signal_unavailable
            - idempotency_conflict
            - idempotency_in_progress
            - idempotency_unavailable
            - ingest_policy_changed
            - ingest_policy_not_found
            - ingest_policy_revoked
            - integrations_unconfigured
            - internal_error
            - invalid_json
            - invalid_pull_request_review_result
            - invalid_request
            - invalid_scope
            - invariant_violation
            - launchdarkly_rate_limited
            - launchdarkly_unavailable
            - live_fleet_unconfigured
            - managed_agents_unavailable
            - merge_key_rejected
            - merge_link_unavailable
            - merge_rate_limited
            - merge_unavailable
            - missing_dependency
            - model_gateway_metadata_missing
            - model_gateway_unconfigured
            - model_gateway_unreachable
            - mutation_transaction_budget_exceeded
            - not_found
            - page_token_expired
            - payload_too_large
            - persistence_busy
            - precondition_failed
            - precondition_required
            - provider_registration_unsupported
            - provider_selection_unsupported
            - rate_limit_exceeded
            - rate_limited
            - repository_automation_unconfigured
            - request_too_large
            - reserved_source_type
            - revision_conflict
            - run_log_store_unavailable
            - runner_image_resolution_failed
            - sandbox_provider_disabled
            - service_unavailable
            - session_analyst_busy
            - session_analyst_model_unavailable
            - session_analyst_unconfigured
            - session_start_admission_unavailable
            - session_start_not_admitted
            - setup_fallback_environment_unsafe
            - setup_run_finished
            - setup_run_in_progress
            - setup_run_limit
            - setup_run_not_started
            - setup_runs_unavailable
            - skill_storage_unconfigured
            - slack_channels_rejected
            - slack_channels_unavailable
            - slack_channels_unconfigured
            - slack_connection_malformed
            - slack_event_intake_unavailable
            - slack_installation_mismatch
            - slack_missing_scope
            - slack_rate_limited
            - slack_reapproval_required
            - source_ownership_mismatch
            - source_revision_conflict
            - spanner_unavailable
            - streaming_unsupported
            - submission_transaction_budget_exceeded
            - task_version_number_conflict
            - team_board_unconfigured
            - too_many_streams
            - unauthorized
            - unsupported_media_type
            - vault_creation_retired
            - version_content_conflict
            - webhook_delivery_too_large
            - workspace_boundary_denied
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          description: Optional structured error details.
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorForbidden:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - forbidden
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          description: Optional structured error details.
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorBadGateway:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - bad_gateway
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          description: Optional structured error details.
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorGatewayTimeout:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - gateway_timeout
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          description: Optional structured error details.
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsModelCostAttemptResponse:
      description: >-
        One model inference or metered provider-side tool call the ledger is
        accountable for, billed or not. An attempt is reserved before the
        request is dispatched, so a call that failed, was never charged, or left
        billing unknown stays visible in the accounting instead of disappearing
        from it.
      properties:
        attempt_id:
          description: >-
            Identifier for this attempt (UUID). Derived deterministically from
            the work that issued the call, so a retried dispatch reuses it
            instead of billing twice; a retry after a dispatch that provably
            never reached billing gets its own derived child id.
          type: string
        catalog_version:
          description: >-
            Pricing catalog version pinned when the attempt was reserved. A
            receipt priced against another version is rejected rather than
            mixed. Empty when the attempt was reserved without a pricing
            catalog.
          type: string
        charge:
          $ref: '#/components/schemas/ManagedAgentsModelCostChargeResponse'
          description: The billed result, present only when state is charged.
        completeness:
          description: >-
            Accounting confidence for this attempt: the charge's own
            completeness when a charge exists, otherwise pending while the
            outcome is still unknown, complete for a not_charged attempt that
            cost nothing, and indeterminate when the call may have been billed
            without a receipt.
          enum:
            - complete
            - pending
            - unpriced
            - partial
            - legacy_partial
            - indeterminate
          type: string
        created_at:
          description: >-
            RFC 3339 timestamp of when the attempt was reserved, before the
            provider request was sent. Attempts page in this order.
          format: date-time
          type: string
        kind:
          description: >-
            model for inference or provider_tool for a metered provider-side
            tool.
          enum:
            - model
            - provider_tool
          type: string
        model:
          description: Model id the call requested, as sent on the wire.
          type: string
        model_ref_id:
          description: >-
            Model reference in the catalog the model was resolved from (UUID).
            Empty when the session named a models-catalog id instead of a
            catalog entry.
          type: string
        parent_session_id:
          description: >-
            Parent of the session the call is attributed to (UUID). Empty when
            that session is the root.
          type: string
        provider:
          description: >-
            Provider the call was dispatched to, e.g. anthropic, openai, or
            gemini.
          type: string
        root_session_id:
          description: Root session of the tree this attempt belongs to (UUID).
          type: string
        session_id:
          description: Session the call is attributed to (UUID).
          type: string
        session_path:
          description: >-
            Position of that session within its tree, as a slash-delimited path
            of session ids. "/" for a root session.
          type: string
        state:
          description: >-
            Ledger lifecycle: prepared once the attempt was reserved, dispatched
            once the request was sent, charged once a receipt was persisted,
            not_charged when the call provably never reached billing, and
            indeterminate when it may have been billed but no usable receipt
            exists.
          enum:
            - prepared
            - dispatched
            - charged
            - not_charged
            - indeterminate
          type: string
        thread_id:
          description: >-
            Thread within a multi-agent session the call belongs to. Empty when
            the attempt was recorded without thread attribution.
          type: string
        updated_at:
          description: RFC 3339 timestamp of the attempt's last state change.
          format: date-time
          type: string
      required:
        - attempt_id
        - root_session_id
        - session_id
        - session_path
        - kind
        - provider
        - state
        - completeness
        - created_at
        - updated_at
      type: object
      example:
        attempt_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        catalog_version: example
        charge:
          adjustments:
            - adjustment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
              created_at: '2026-02-18T09:30:00.000Z'
              created_by: example
              kind: provider_authority
              model_cost_usd: example
              reason: example
          charge_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
          completeness: complete
          components:
            - cache_state: none
              category: input
              component_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
              dimension: example
              modality: text
              model_cost_usd: example
              price:
                catalog_version: example
                currency: USD
                denominator_units: example
                model: example
                numerator_nano_usd: example
                provider: example
                region: example
                rule_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
                service_tier: example
              price_redacted: true
              quantity: example
              unit: token
          locally_priced_model_cost_usd: example
          model_cost_usd: example
          original_model_cost_usd: example
          provider_reported_model_cost_usd: example
          receipt:
            provider_request_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            quantities:
              - cache_state: none
                category: input
                dimension: example
                modality: text
                quantity: example
                unit: token
            recovery:
              method: example
              recovered_at: '2026-02-18T09:30:00.000Z'
              reference: example
            redacted_fields:
              - example
            region: example
            requested_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            resolved_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            service_tier: example
            source: example
          receipt_sha256: example
          recorded_at: '2026-02-18T09:30:00.000Z'
        completeness: complete
        created_at: '2026-02-18T09:30:00.000Z'
        kind: model
        model: example
        model_ref_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        parent_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        provider: example
        root_session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        session_path: example
        state: prepared
        thread_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        updated_at: '2026-02-18T09:30:00.000Z'
    ManagedAgentsSessionModelCostSummariesResponse:
      description: >-
        One session's three scope rollups, read from a single database snapshot
        so self, subtree, and tree cannot disagree with one another.
      properties:
        self:
          $ref: '#/components/schemas/ManagedAgentsSessionModelCostSummaryResponse'
          description: >-
            Totals for this session's own attempts, excluding every child
            session.
        session_id:
          description: Session these three rollups were requested for (UUID).
          type: string
        subtree:
          $ref: '#/components/schemas/ManagedAgentsSessionModelCostSummaryResponse'
          description: Totals for this session and every session beneath it in the tree.
        tree:
          $ref: '#/components/schemas/ManagedAgentsSessionModelCostSummaryResponse'
          description: >-
            Totals for every session sharing the same root session, including
            this session's ancestors and siblings.
      required:
        - session_id
        - self
        - subtree
        - tree
      type: object
      example:
        self:
          adjustment_count: example
          attempt_count: example
          charge_count: example
          completeness: complete
          model_cost_usd: example
          scope: self
          session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        subtree:
          adjustment_count: example
          attempt_count: example
          charge_count: example
          completeness: complete
          model_cost_usd: example
          scope: self
          session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        tree:
          adjustment_count: example
          attempt_count: example
          charge_count: example
          completeness: complete
          model_cost_usd: example
          scope: self
          session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
    ManagedAgentsSessionModelCostSummaryResponse:
      description: >-
        Model-cost rollup for one session scope: the exact ledger amount, how
        complete the accounting behind it is, and the counts it was derived
        from. attempt_count is every provider call the ledger is accountable
        for, charge_count only those that produced a receipt, and
        adjustment_count the signed corrections applied since. Model spend only:
        sandbox, tool, and storage cost are not included.
      properties:
        adjustment_count:
          description: Exact base-10 integer string.
          type: string
        attempt_count:
          description: Exact base-10 integer string.
          type: string
        charge_count:
          description: Exact base-10 integer string.
          type: string
        completeness:
          description: >-
            Weakest accounting state present in scope, so a rollup never
            overstates confidence: complete when every attempt is fully priced,
            pending when no attempt has been recorded yet or an outcome is still
            unknown, unpriced when no catalog rule matched the provider's
            quantities, partial when only part of the cost is known or several
            states are mixed, legacy_partial for charges recorded before the
            current reconciliation rules, and indeterminate when an attempt may
            have been billed without a usable receipt.
          enum:
            - complete
            - pending
            - unpriced
            - partial
            - legacy_partial
            - indeterminate
          type: string
        model_cost_usd:
          description: >-
            Exact canonical decimal USD string. It is model cost only, not total
            session spend. Customers receive the amount their organization is
            billed; only trusted internal callers receive raw ledger cost here.
          type: string
        scope:
          description: >-
            Which sessions contributed: self counts this session's own attempts,
            subtree adds every session beneath it, and tree covers every session
            sharing the same root session.
          enum:
            - self
            - subtree
            - tree
          type: string
        session_id:
          description: >-
            Session this rollup was requested for (UUID). Scope decides which
            sessions in its tree contributed to the figures.
          type: string
      required:
        - session_id
        - scope
        - model_cost_usd
        - completeness
        - attempt_count
        - charge_count
        - adjustment_count
      type: object
      example:
        adjustment_count: example
        attempt_count: example
        charge_count: example
        completeness: complete
        model_cost_usd: example
        scope: self
        session_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
    ManagedAgentsModelCostChargeResponse:
      description: >-
        The billed result of one attempt: the provider receipt, the components
        it was priced into, every adjustment since, and the amounts those
        produce. A charge is written once and never rewritten, so a later
        correction arrives as an adjustment rather than as an edit. Customers
        receive every amount as billed to their organization, with price
        snapshots and provider-reported totals redacted; only trusted internal
        callers receive raw ledger amounts.
      properties:
        adjustments:
          description: >-
            Signed corrections applied to this charge, oldest first. Empty when
            the locally priced total was accepted as recorded.
          items:
            $ref: '#/components/schemas/ManagedAgentsModelCostAdjustmentResponse'
          type:
            - array
            - 'null'
        charge_id:
          description: >-
            Identifier for this charge (UUID), always the attempt_id it settles:
            a charged attempt has exactly one charge.
          type: string
        completeness:
          description: >-
            Accounting confidence for this charge alone: complete when every
            component is priced, unpriced when none matched a catalog rule,
            partial when only some cost is known or a reported total could not
            be trusted, and legacy_partial for charges recorded before the
            current reconciliation rules. A persisted charge is never pending or
            indeterminate; those states belong to an attempt without one.
          enum:
            - complete
            - pending
            - unpriced
            - partial
            - legacy_partial
            - indeterminate
          type: string
        components:
          description: >-
            Priced lines of this charge, one per receipt dimension, ordered by
            component_id.
          items:
            $ref: '#/components/schemas/ManagedAgentsModelCostComponentResponse'
          type:
            - array
            - 'null'
        locally_priced_model_cost_usd:
          description: >-
            Sum of the components' amounts, i.e. what the pinned price catalog
            says this call cost. Exact canonical decimal USD string.
          type: string
        model_cost_usd:
          description: >-
            Current ledger amount for this charge, i.e. the locally priced total
            plus every adjustment. This is the amount that rolls up into the
            session summaries. Exact canonical decimal USD string.
          type: string
        original_model_cost_usd:
          description: >-
            Ledger amount when this charge was first recorded: the
            provider-reported total when one was authoritative, otherwise the
            locally priced total. Exact canonical decimal USD string.
          type: string
        provider_reported_model_cost_usd:
          description: >-
            Total the provider reported for this call, reconciled from its exact
            lexical value. Absent when none was reported or none could be
            trusted. When it differs from the locally priced total, a
            provider_authority adjustment reconciles the two. Exact canonical
            decimal USD string.
          type: string
        receipt:
          $ref: '#/components/schemas/ManagedAgentsModelCostReceiptResponse'
          description: Immutable provider evidence this charge was derived from.
        receipt_sha256:
          description: >-
            Lowercase hex SHA-256 over the canonical receipt envelope, which is
            the provider's raw usage body together with the receipt evidence.
            Re-hashing the receipt proves it has not changed since the charge
            was recorded.
          type: string
        recorded_at:
          description: >-
            RFC 3339 commit timestamp of when the charge was written to the
            ledger.
          format: date-time
          type: string
      required:
        - charge_id
        - completeness
        - receipt
        - receipt_sha256
        - components
        - adjustments
        - locally_priced_model_cost_usd
        - original_model_cost_usd
        - model_cost_usd
        - recorded_at
      type: object
      example:
        adjustments:
          - adjustment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            created_at: '2026-02-18T09:30:00.000Z'
            created_by: example
            kind: provider_authority
            model_cost_usd: example
            reason: example
        charge_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        completeness: complete
        components:
          - cache_state: none
            category: input
            component_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
            dimension: example
            modality: text
            model_cost_usd: example
            price:
              catalog_version: example
              currency: USD
              denominator_units: example
              model: example
              numerator_nano_usd: example
              provider: example
              region: example
              rule_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
              service_tier: example
            price_redacted: true
            quantity: example
            unit: token
        locally_priced_model_cost_usd: example
        model_cost_usd: example
        original_model_cost_usd: example
        provider_reported_model_cost_usd: example
        receipt:
          provider_request_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
          quantities:
            - cache_state: none
              category: input
              dimension: example
              modality: text
              quantity: example
              unit: token
          recovery:
            method: example
            recovered_at: '2026-02-18T09:30:00.000Z'
            reference: example
          redacted_fields:
            - example
          region: example
          requested_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
          resolved_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
          service_tier: example
          source: example
        receipt_sha256: example
        recorded_at: '2026-02-18T09:30:00.000Z'
    ManagedAgentsModelCostAdjustmentResponse:
      description: >-
        A signed correction to one charge, recorded after the charge itself.
        Adjustments are append-only: original_model_cost_usd keeps the amount as
        first recorded, and model_cost_usd carries the locally priced total plus
        every adjustment.
      properties:
        adjustment_id:
          description: >-
            Identifier for this adjustment within its charge. The ledger's own
            reconciliation of a provider-reported total always uses
            provider-authority.
          type: string
        created_at:
          description: RFC 3339 timestamp of when the adjustment was committed.
          format: date-time
          type: string
        created_by:
          description: >-
            Principal that recorded the adjustment. The automatic reconciliation
            of a provider-reported total is recorded under a system:… principal.
          type: string
        kind:
          description: >-
            provider_authority reconciles the locally priced total to the total
            the provider reported for the same call; correction is an amendment
            recorded against an existing charge.
          enum:
            - provider_authority
            - correction
          type: string
        model_cost_usd:
          description: Exact signed canonical decimal USD string.
          type: string
        reason:
          description: >-
            Why the adjustment was recorded, e.g. that the provider-reported
            total overrides the local price snapshot.
          type: string
      required:
        - adjustment_id
        - kind
        - model_cost_usd
        - reason
        - created_by
        - created_at
      type: object
      example:
        adjustment_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        created_at: '2026-02-18T09:30:00.000Z'
        created_by: example
        kind: provider_authority
        model_cost_usd: example
        reason: example
    ManagedAgentsModelCostComponentResponse:
      description: >-
        One priced line of a charge: a receipt quantity joined to the rate it
        was charged at, and the exact amount that produced. Components sum to
        locally_priced_model_cost_usd, and an unpriced component contributes
        nothing to it.
      properties:
        cache_state:
          description: >-
            Prompt-cache disposition: none for uncached tokens, read for a cache
            hit, and write_5m or write_1h for tokens written into the provider's
            cache at that time to live.
          enum:
            - none
            - read
            - write_5m
            - write_1h
          type: string
        category:
          description: >-
            What the quantity was consumed for: model input or output,
            provider-side tools, or compute runtime.
          enum:
            - input
            - output
            - reasoning
            - tool_prompt
            - provider_tool
            - compute
          type: string
        component_id:
          description: >-
            Identifier for this component within its charge. Equal to the
            dimension it prices, and unique per charge.
          type: string
        dimension:
          description: >-
            Provider usage field this component prices, matching exactly one
            receipt quantity of the same dimension.
          type: string
        modality:
          description: >-
            Content or resource type measured. compute marks sandbox runtime
            rather than model content.
          enum:
            - text
            - image
            - audio
            - video
            - tool
            - compute
          type: string
        model_cost_usd:
          description: Exact canonical decimal USD string.
          type: string
        price:
          $ref: '#/components/schemas/ManagedAgentsModelCostPriceResponse'
          description: >-
            Rate this component was charged at. Absent when no catalog rule
            matched the dimension, in which case the component costs nothing and
            the charge cannot be complete, and absent with price_redacted set
            for callers that do not read raw cost.
        price_redacted:
          description: >-
            True when this component was priced but its private price snapshot
            was omitted.
          type: boolean
        quantity:
          description: >-
            Exact base-10 integer string. Withheld from customer callers, which
            see it named in the receipt's redacted_fields.
          type: string
        unit:
          description: >-
            What quantity counts: tokens, requests, or elapsed compute
            milliseconds.
          enum:
            - token
            - request
            - millisecond
          type: string
      required:
        - component_id
        - dimension
        - category
        - modality
        - cache_state
        - unit
        - model_cost_usd
      type: object
      example:
        cache_state: none
        category: input
        component_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        dimension: example
        modality: text
        model_cost_usd: example
        price:
          catalog_version: example
          currency: USD
          denominator_units: example
          model: example
          numerator_nano_usd: example
          provider: example
          region: example
          rule_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
          service_tier: example
        price_redacted: true
        quantity: example
        unit: token
    ManagedAgentsModelCostReceiptResponse:
      description: >-
        Immutable provider evidence behind one charge: what the provider says it
        served, and how much of it. Amounts are never read from here directly;
        the components carry the priced result, and receipt_sha256 on the charge
        covers this evidence together with the provider's raw usage body.
      properties:
        provider_request_id:
          description: >-
            Provider's own id for the request, which is how the call is found in
            provider logs. Empty when the provider returned none. Withheld from
            customer callers, which instead see it named in redacted_fields.
          type: string
        quantities:
          description: >-
            Every billable quantity the provider reported, one per dimension. A
            charge's components reconcile exactly to these. Empty for customer
            callers, which see quantities named in redacted_fields.
          items:
            $ref: '#/components/schemas/ManagedAgentsModelCostReceiptQuantityResponse'
          type:
            - array
            - 'null'
        recovery:
          $ref: '#/components/schemas/ManagedAgentsCostReceiptRecovery'
          description: >-
            How this receipt was obtained when it did not arrive on the original
            provider response. Absent for the ordinary inline case.
        redacted_fields:
          description: >-
            Paths withheld from this receipt, e.g. provider_request_id,
            resolved_model_id, or components[].price. Also carries
            invalid_header:<name> markers for billing headers that failed
            validation and were dropped from evidence rather than trusted.
          items:
            type: string
          type: array
        region:
          description: >-
            Provider region or inference geography the call was served from,
            when reported. Part of the pricing-rule match.
          type: string
        requested_model_id:
          description: Model id the request asked for, as sent on the wire.
          type: string
        resolved_model_id:
          description: >-
            Model id the provider reports it actually served, and the id the
            components were priced against. Empty when the provider returned
            none, and withheld from customer callers.
          type: string
        service_tier:
          description: >-
            Provider service tier the call was served at, when the provider
            reports one. Part of the pricing-rule match.
          type: string
        source:
          description: >-
            Provider that authored this usage body, always the attempt's own
            provider, e.g. anthropic, openai, or gemini.
          type: string
      required:
        - source
        - quantities
      type: object
      example:
        provider_request_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        quantities:
          - cache_state: none
            category: input
            dimension: example
            modality: text
            quantity: example
            unit: token
        recovery:
          method: example
          recovered_at: '2026-02-18T09:30:00.000Z'
          reference: example
        redacted_fields:
          - example
        region: example
        requested_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        resolved_model_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        service_tier: example
        source: example
    ManagedAgentsModelCostPriceResponse:
      description: >-
        Price one component was charged at, snapshotted from the pricing catalog
        when the charge was recorded so the amount stays reproducible after the
        catalog changes. The rate is numerator_nano_usd per denominator_units of
        quantity, in nano-USD (1,000,000,000 nano-USD = 1 USD), and a
        component's amount is quantity * numerator / denominator rounded half to
        even exactly once. Returned only to trusted internal callers that read
        raw cost.
      properties:
        catalog_version:
          description: >-
            Pricing catalog version this snapshot was taken from, always the
            version pinned on the attempt. A receipt priced against a different
            version is rejected rather than mixed.
          type: string
        currency:
          description: >-
            Currency of the rate. Always USD; the ledger holds no other
            currency.
          enum:
            - USD
          type: string
        denominator_units:
          description: Exact base-10 integer string.
          type: string
        model:
          description: >-
            Model id the rate was applied to: the receipt's resolved model, or
            the requested model when the provider reported no resolution. Empty
            only when neither recorded one.
          type: string
        numerator_nano_usd:
          description: Exact base-10 integer string.
          type: string
        provider:
          description: Provider this rate priced, always the attempt's own provider.
          type: string
        region:
          description: >-
            Region the rate was applied at, always equal to the receipt's
            region. Empty when the provider reported none.
          type: string
        rule_id:
          description: >-
            Rule within that catalog version that matched this component. The
            most specific matching rule wins, and an ambiguous tie is rejected
            rather than guessed.
          type: string
        service_tier:
          description: >-
            Service tier the rate was applied at, always equal to the receipt's
            service_tier. Empty when the provider reported no tier.
          type: string
      required:
        - catalog_version
        - rule_id
        - provider
        - currency
        - numerator_nano_usd
        - denominator_units
      type: object
      example:
        catalog_version: example
        currency: USD
        denominator_units: example
        model: example
        numerator_nano_usd: example
        provider: example
        region: example
        rule_id: 9f8b1c2d-3e4f-5a6b-7c8d-9e0f1a2b3c4d
        service_tier: example
    ManagedAgentsModelCostReceiptQuantityResponse:
      description: >-
        One billable quantity exactly as the provider reported it, before any
        pricing. Receipt quantities are the audit trail behind a charge: each
        priced component reconciles to exactly one quantity of the same
        dimension, with the same category, modality, cache state, unit, and
        count.
      properties:
        cache_state:
          description: >-
            Prompt-cache disposition: none for uncached tokens, read for a cache
            hit, and write_5m or write_1h for tokens written into the provider's
            cache at that time to live.
          enum:
            - none
            - read
            - write_5m
            - write_1h
          type: string
        category:
          description: >-
            What the quantity was consumed for: model input or output,
            provider-side tools, or compute runtime.
          enum:
            - input
            - output
            - reasoning
            - tool_prompt
            - provider_tool
            - compute
          type: string
        dimension:
          description: >-
            Field path in the provider's usage body this quantity was read from,
            e.g. input_tokens, cache_creation.ephemeral_5m_input_tokens, or
            output.reasoning. Unique within a receipt, and the key its priced
            component joins on. A dimension containing .unsupported is a
            provider aggregate that cannot be attributed to a rate, and is never
            priced.
          type: string
        modality:
          description: >-
            Content or resource type measured. compute marks sandbox runtime
            rather than model content.
          enum:
            - text
            - image
            - audio
            - video
            - tool
            - compute
          type: string
        quantity:
          description: Exact base-10 integer string.
          type: string
        unit:
          description: >-
            What quantity counts: tokens, requests, or elapsed compute
            milliseconds.
          enum:
            - token
            - request
            - millisecond
          type: string
      required:
        - dimension
        - category
        - modality
        - cache_state
        - quantity
        - unit
      type: object
      example:
        cache_state: none
        category: input
        dimension: example
        modality: text
        quantity: example
        unit: token
    ManagedAgentsCostReceiptRecovery:
      description: >-
        How a provider receipt was obtained after the original response was
        lost, so a charge settled out of band is still auditable back to the
        provider.
      properties:
        method:
          description: >-
            How the receipt was recovered: provider_lookup means it was fetched
            from the provider by request id, and idempotent_retry means it came
            from replaying the call under the attempt's provider idempotency
            key.
          type: string
        recovered_at:
          description: RFC 3339 timestamp of when the receipt was recovered.
          format: date-time
          type: string
        reference:
          description: >-
            Identifier the recovery was keyed on: the receipt's
            provider_request_id for provider_lookup, or the attempt's provider
            idempotency key for idempotent_retry.
          type: string
      required:
        - method
        - reference
        - recovered_at
      type: object
      example:
        method: example
        recovered_at: '2026-02-18T09:30:00.000Z'
        reference: example
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A Recursion API key, created in the console under API keys.

````