> ## 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.

# Roll up token and cost totals for a batch of sessions

> Rolls up token counts and cost for the sessions named in session_ids and returns one row per session. Ids that do not exist in this organization are omitted rather than erroring, so compare the row count against what you asked for. The request is rejected if it names more ids than the per-request maximum.



## OpenAPI

````yaml /recursion/openapi.yaml get /managed-agents/v1/sessions/usage
openapi: 3.1.0
info:
  title: Managed Agents API
  version: 0.14.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/usage:
    get:
      tags:
        - Sessions
      summary: Roll up token and cost totals for a batch of sessions
      description: >-
        Rolls up token counts and cost for the sessions named in session_ids and
        returns one row per session. Ids that do not exist in this organization
        are omitted rather than erroring, so compare the row count against what
        you asked for. The request is rejected if it names more ids than the
        per-request maximum.
      operationId: managedAgentsListSessionUsage
      parameters:
        - description: >-
            Comma-separated session ids to roll up, matching the ids returned by
            GET /managed-agents/v1/sessions. Ids that do not exist in this
            organization or are outside the caller's access policy are omitted
            from the response rather than erroring.
          in: query
          name: session_ids
          required: true
          schema:
            description: >-
              Comma-separated session ids to roll up, matching the ids returned
              by GET /managed-agents/v1/sessions. Ids that do not exist in this
              organization or are outside the caller's access policy are omitted
              from the response rather than erroring.
            type: string
        - $ref: '#/components/parameters/RecursionTenantId'
        - $ref: '#/components/parameters/RecursionOrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionUsageListResponse'
          description: >-
            Response body of GET /managed-agents/v1/sessions/usage: token and
            cost totals for an explicit batch of session ids, so a list view can
            show a cost per row without reading every session's events.
            session_ids is required and bounded; too many ids is rejected
            outright rather than truncated, because a silently short answer is
            indistinguishable from idle sessions.
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '400':
          description: Bad Request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest'
                x-recursion-error-codes:
                  - invalid_request
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized'
                x-recursion-error-codes:
                  - unauthorized
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden'
                x-recursion-error-codes:
                  - forbidden
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '404':
          description: Not Found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound'
                x-recursion-error-codes:
                  - not_found
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '413':
          description: Payload Too Large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge'
                x-recursion-error-codes:
                  - payload_too_large
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '429':
          headers:
            Retry-After:
              description: When to retry, as delay seconds or an HTTP date.
              schema:
                type: string
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
          description: Too Many Requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded'
                x-recursion-error-codes:
                  - rate_limit_exceeded
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError'
                x-recursion-error-codes:
                  - internal_error
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '502':
          description: A dependent service returned an invalid response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure'
                x-recursion-error-codes:
                  - bad_gateway
          headers:
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
        '503':
          headers:
            Retry-After:
              description: When to retry, as delay seconds or an HTTP date.
              schema:
                type: string
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
          description: Service Unavailable.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: >-
                      #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable
                  - $ref: >-
                      #/components/schemas/ManagedAgentsApiErrorServiceUnavailable
                discriminator:
                  propertyName: code
                  mapping:
                    managed_agents_unavailable: >-
                      #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable
                    service_unavailable: >-
                      #/components/schemas/ManagedAgentsApiErrorServiceUnavailable
                x-recursion-error-codes:
                  - managed_agents_unavailable
                  - service_unavailable
        '504':
          headers:
            Retry-After:
              description: When to retry, as delay seconds or an HTTP date.
              schema:
                type: string
            recursion-organization-id:
              $ref: '#/components/headers/RecursionOrganizationId'
            recursion-tenant-id:
              $ref: '#/components/headers/RecursionTenantId'
          description: A dependent service timed out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout'
                x-recursion-error-codes:
                  - gateway_timeout
components:
  parameters:
    RecursionTenantId:
      name: x-tenant-id
      in: header
      required: false
      description: >-
        Optional tenant consistency check. When present, it must name the tenant
        bound to the API key, including when x-organization-id is `default`.
      schema:
        type: string
        minLength: 1
    RecursionOrganizationId:
      name: x-organization-id
      in: header
      required: false
      description: >-
        Organization in which to act. Required for a tenant-scoped API key.
        Optional for an organization-scoped key, where it must name that same
        organization. The value may be an organization id or `default`.
      schema:
        type: string
        minLength: 1
  schemas:
    SessionUsageListResponse:
      description: >-
        Response body of GET /managed-agents/v1/sessions/usage: token and cost
        totals for an explicit batch of session ids, so a list view can show a
        cost per row without reading every session's events. session_ids is
        required and bounded; too many ids is rejected outright rather than
        truncated, because a silently short answer is indistinguishable from
        idle sessions.
      properties:
        session_usage:
          description: >-
            One roll-up row per requested session id that the caller can see.
            Null rather than an empty array when none of the requested ids
            resolved. Ids naming nothing visible are omitted, so the result may
            be shorter than session_ids and the order should not be assumed to
            match.
          items:
            $ref: '#/components/schemas/SessionUsage'
          type:
            - array
            - 'null'
      required:
        - session_usage
      type: object
      additionalProperties: false
    ManagedAgentsApiErrorInvalidRequest:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - invalid_request
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorUnauthorized:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - unauthorized
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      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:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorNotFound:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - not_found
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorPayloadTooLarge:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - payload_too_large
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorRateLimitExceeded:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - rate_limit_exceeded
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorInternalError:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - internal_error
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorDependencyFailure:
      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:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorManagedAgentsUnavailable:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - managed_agents_unavailable
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorServiceUnavailable:
      type: object
      properties:
        code:
          type: string
          minLength: 1
          description: Stable machine-readable error code.
          enum:
            - service_unavailable
        message:
          type: string
          minLength: 1
          description: Human-readable error message.
        details:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    ManagedAgentsApiErrorDependencyTimeout:
      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:
          $ref: '#/components/schemas/ManagedAgentsApiErrorDetails'
          description: >-
            Optional structured error details. Reserved transport fields are
            typed; code-specific fields remain forward compatible.
      required:
        - code
        - message
      additionalProperties: false
      description: Standard flat error response.
    SessionUsage:
      description: >-
        Token and cost totals for one session, summed over that session's own
        events. Scoped to the session's own timeline and not its subtree, so a
        delegating session's totals exclude its children.
      properties:
        cache_read_tokens:
          description: >-
            Prompt tokens served from the provider's prompt cache, billed at the
            cached rate.
          format: int64
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        cache_write_tokens:
          description: Prompt tokens written into the provider's prompt cache.
          format: int64
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        cost_micros:
          description: >-
            Cost the session's own events reported, in micro-USD (1,000,000 = 1
            USD). Diagnostic only: this is not what you are charged. Read a
            session's billed cost from costUsd on managedAgentsGetSession.
          format: int64
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        event_count:
          description: >-
            How many of the session's own events were summed to produce these
            totals.
          format: int64
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        input_tokens:
          description: Prompt tokens billed for this unit of work.
          format: int64
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        output_tokens:
          description: Completion tokens billed for this unit of work.
          format: int64
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        session_id:
          description: Session these totals cover (UUID).
          type: string
      required:
        - session_id
        - event_count
        - input_tokens
        - output_tokens
        - cache_read_tokens
        - cache_write_tokens
        - cost_micros
      type: object
      additionalProperties: false
    ManagedAgentsApiErrorDetails:
      type: object
      properties:
        field:
          description: >-
            Request field or header responsible for the error, when one can be
            identified.
          type: string
        issues:
          description: >-
            Boundary-validation failures as path-prefixed human-readable
            messages.
          type: array
          items:
            type: string
        requestId:
          description: Request correlation identifier for support and log lookup.
          type: string
        retryable:
          description: >-
            Server advice about failure transience. `true` means transient,
            `false` means non-transient, and absence gives no advice. Automatic
            replay is allowed only when this field is not `false` and the
            operation-specific retry and idempotency contract permits replay.
          type: boolean
      additionalProperties:
        $ref: '#/components/schemas/PlatformSafeJsonValue'
      description: >-
        Optional structured error details. Reserved transport fields are typed;
        code-specific fields remain forward compatible.
    PlatformSafeJsonValue:
      description: >-
        A JSON value whose integer members stay within the exact ECMAScript
        safe-integer range at every nesting level.
      oneOf:
        - type: 'null'
        - type: boolean
        - type: string
        - type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        - type: number
          not:
            type: integer
        - type: array
          items:
            $ref: '#/components/schemas/PlatformSafeJsonValue'
        - additionalProperties:
            $ref: '#/components/schemas/PlatformSafeJsonValue'
          type: object
  headers:
    RecursionOrganizationId:
      description: Organization id resolved for this request.
      schema:
        type: string
        minLength: 1
    RecursionTenantId:
      description: Tenant id resolved for this request.
      schema:
        type: string
        minLength: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A Recursion API key, created in the console under API keys.

````