> ## Documentation Index > Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List raw UsageLedger entries > Returns a page of append-only UsageEntry records, each carrying exactly one model, unit-metered, session-runtime, sandbox-compute, or snapshot-retention measurement plus its immutable Workspace, Session, Run, Agent, Principal, SurfaceScope, and Automation attribution. Filter by any of those dimensions and by `order`; each page is clamped to at most 1,000 entries. This is the raw ledger — prefer `usage.getUsageSeries` when you want totals rather than individual facts. Checkfu support posture: alpha; hosted. Required evidence journey: usage-series. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities. ## OpenAPI ````yaml /openapi.json get /v1/usage openapi: 3.1.0 info: title: Checkfu API version: '2026-08-27' description: >- Authentication is declared per operation: API-key, runtime, or connector bearer; Automation signature; or credential-free pairing redemption. Every general Checkfu REST request requires the dated `Checkfu-Version` header (one of: 2026-08-27); the three MCP JSON-RPC transports use `MCP-Protocol-Version`, A2A uses `A2A-Version`, and the provider OAuth callback carries neither Checkfu header. API keys resolve one Workspace without a request selector; authenticated responses identify it with `Checkfu-Workspace-Id`. servers: - url: https://api.checkfu.com security: - bearerAuth: [] tags: - name: organizations - name: sourceRepositories - name: tenants - name: workspaces - name: principals - name: principalGroups - name: principalAccessCredentials - name: apiKeys - name: agents - name: harnesses - name: harnessRuntime - name: sandboxProfiles - name: computerProfiles - name: permissionAssignments - name: actionPolicies - name: files - name: memoryStores - name: dreams - name: modelCredentials - name: modelRoutingProfiles - name: blueprintInstallations - name: toolSources - name: skills - name: skillSources - name: agentSources - name: skillProposals - name: instructionProposals - name: catalog - name: concepts - name: support - name: connections - name: connectionVaults - name: connectionAssignments - name: connectedRuntimes - name: projects - name: collaboration - name: automationGraphs - name: automations - name: actionApprovals - name: standingApprovals - name: usage - name: models - name: outcomes - name: budgets - name: billing - name: sessionTemplates - name: sessions - name: audit - name: sessionExports - name: runs - name: runnerPools - name: transcripts - name: sessionSelection - name: sessionWatches - name: webhookEndpoints - name: sessionClient - name: integrationGateway - name: agentDeployments - name: workEnvironments - name: computers - name: computerScreens - name: computerBrowserObservations - name: computerBrowserActions - name: environments - name: vaults - name: apiMcp - name: a2a paths: /v1/usage: get: tags: - usage summary: List raw UsageLedger entries description: >- Returns a page of append-only UsageEntry records, each carrying exactly one model, unit-metered, session-runtime, sandbox-compute, or snapshot-retention measurement plus its immutable Workspace, Session, Run, Agent, Principal, SurfaceScope, and Automation attribution. Filter by any of those dimensions and by `order`; each page is clamped to at most 1,000 entries. This is the raw ledger — prefer `usage.getUsageSeries` when you want totals rather than individual facts. Checkfu support posture: alpha; hosted. Required evidence journey: usage-series. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities. operationId: usage.listUsage parameters: - name: checkfu-version in: header schema: type: string enum: - '2026-08-27' required: true - name: limit in: query schema: type: integer minimum: 1 required: false - name: page in: query schema: type: string allOf: - pattern: ^c1_[0-9a-z]+$ required: false - name: principal_id in: query schema: $ref: '#/components/schemas/PrincipalId' required: false - name: agent_id in: query schema: $ref: '#/components/schemas/AgentId' required: false - name: surface_scope_id in: query schema: $ref: '#/components/schemas/SurfaceScopeId' required: false - name: automation_id in: query schema: $ref: '#/components/schemas/AutomationId' required: false - name: session_id in: query schema: $ref: '#/components/schemas/SessionId' required: false - name: run in: query schema: $ref: '#/components/schemas/RunId' required: false - name: order in: query schema: type: string enum: - asc - desc required: false responses: '200': description: Success content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/UsageEntrySubject' next_page: anyOf: - type: string - type: 'null' required: - data - next_page additionalProperties: false headers: checkfu-workspace-id: description: The Workspace resolved from the authenticated bearer credential. required: true schema: $ref: '#/components/schemas/WorkspaceId' '400': description: Typed Checkfu wire error content: application/json: schema: $ref: '#/components/schemas/ValidationMalformedError' '401': description: Typed Checkfu wire error content: application/json: schema: type: object required: - error properties: error: type: object required: - type - message - more properties: type: type: string enum: - auth.invalid_key message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#auth-invalid-key description: >- Stable public documentation and remedy for this error type. additionalProperties: false additionalProperties: false '403': description: >- The organization, tenant, or workspace backing this key is administratively disabled. | Deployment governance or retention policy denied the request. content: application/json: schema: anyOf: - type: object required: - error properties: error: type: object properties: type: type: string enum: - auth.disabled_tenancy message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#auth-disabled-tenancy description: >- Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false additionalProperties: false - $ref: '#/components/schemas/PolicyDeniedError' '429': description: Typed Checkfu wire error headers: retry-after: description: >- Delay in seconds for rate limits or deployment quotas with a known release or UTC reset boundary required: false schema: type: integer minimum: 1 content: application/json: schema: type: object required: - error properties: error: type: object required: - type - message - more properties: type: type: string enum: - budget.exceeded message: type: string more: type: string enum: - >- https://docs.checkfu.com/reference/errors#budget-exceeded description: >- Stable public documentation and remedy for this error type. additionalProperties: false additionalProperties: false '500': description: >- An unexpected internal failure occurred; the message contains an opaque incident reference. content: application/json: schema: $ref: '#/components/schemas/RuntimeInternalError' security: - bearerAuth: [] components: schemas: PrincipalId: type: string allOf: - pattern: ^prin_[0-9a-f]{32}$ AgentId: type: string allOf: - pattern: ^agent_[0-9a-f]{32}$ SurfaceScopeId: type: string allOf: - pattern: ^surf_[0-9a-f]{32}$ AutomationId: type: string allOf: - pattern: ^auto_[0-9a-f]{32}$ SessionId: type: string allOf: - pattern: ^sess_[0-9a-f]{32}$ RunId: type: string allOf: - pattern: ^run_[0-9a-f]{32}$ UsageEntrySubject: anyOf: - type: object properties: id: $ref: '#/components/schemas/UsageEntryId' session_id: $ref: '#/components/schemas/SessionId' run: $ref: '#/components/schemas/RunId' attempt: $ref: '#/components/schemas/RunAttemptId' agent_definition_id: $ref: '#/components/schemas/AgentId' surface_scope_id: anyOf: - $ref: '#/components/schemas/SurfaceScopeId' - type: 'null' automation_id: anyOf: - $ref: '#/components/schemas/AutomationId' - type: 'null' sequence: type: integer allOf: - exclusiveMinimum: 0 workspace_id: $ref: '#/components/schemas/WorkspaceId' principal_id: $ref: '#/components/schemas/Union_280' anonymous_subject_ref: $ref: '#/components/schemas/Union_281' recorded_at: $ref: '#/components/schemas/UsageTimestamp' measurement: type: object properties: kind: type: string enum: - model model_routing_profile_id: $ref: '#/components/schemas/ModelRoutingProfileId' candidate: $ref: '#/components/schemas/Objects_163' tokens: $ref: '#/components/schemas/Objects_73' measured_at: $ref: '#/components/schemas/UsageTimestamp' supply_class: $ref: '#/components/schemas/Union_282' required: - kind - model_routing_profile_id - candidate - tokens - measured_at - supply_class additionalProperties: false cost: type: object properties: tokens: type: integer allOf: - minimum: 0 model_spend_microusd: anyOf: - type: integer allOf: - minimum: 0 - type: 'null' active_ms: false storage_mib_ms: false running_ms: false billed_microusd: false required: - tokens additionalProperties: false required: - id - session_id - run - attempt - agent_definition_id - sequence - workspace_id - principal_id - anonymous_subject_ref - recorded_at - measurement - cost additionalProperties: false - type: object properties: id: $ref: '#/components/schemas/UsageEntryId' session_id: $ref: '#/components/schemas/SessionId' run: $ref: '#/components/schemas/RunId' attempt: $ref: '#/components/schemas/RunAttemptId' agent_definition_id: $ref: '#/components/schemas/AgentId' surface_scope_id: anyOf: - $ref: '#/components/schemas/SurfaceScopeId' - type: 'null' automation_id: anyOf: - $ref: '#/components/schemas/AutomationId' - type: 'null' sequence: type: integer allOf: - exclusiveMinimum: 0 workspace_id: $ref: '#/components/schemas/WorkspaceId' principal_id: $ref: '#/components/schemas/Union_280' anonymous_subject_ref: $ref: '#/components/schemas/Union_281' recorded_at: $ref: '#/components/schemas/UsageTimestamp' measurement: type: object properties: kind: type: string enum: - model_unit model_routing_profile_id: $ref: '#/components/schemas/ModelRoutingProfileId' candidate: $ref: '#/components/schemas/Objects_163' usage: $ref: '#/components/schemas/Objects_164' measured_at: $ref: '#/components/schemas/UsageTimestamp' supply_class: $ref: '#/components/schemas/Union_282' required: - kind - model_routing_profile_id - candidate - usage - measured_at - supply_class additionalProperties: false cost: type: object properties: tokens: false active_ms: false storage_mib_ms: false running_ms: false billed_microusd: false unit: $ref: '#/components/schemas/Union_283' quantity_millionths: type: integer allOf: - minimum: 0 model_spend_microusd: anyOf: - type: integer allOf: - minimum: 0 - type: 'null' required: - unit - quantity_millionths additionalProperties: false required: - id - session_id - run - attempt - agent_definition_id - sequence - workspace_id - principal_id - anonymous_subject_ref - recorded_at - measurement - cost additionalProperties: false - type: object properties: id: $ref: '#/components/schemas/UsageEntryId' session_id: $ref: '#/components/schemas/SessionId' run: $ref: '#/components/schemas/RunId' attempt: $ref: '#/components/schemas/RunAttemptId' agent_definition_id: $ref: '#/components/schemas/AgentId' surface_scope_id: anyOf: - $ref: '#/components/schemas/SurfaceScopeId' - type: 'null' automation_id: anyOf: - $ref: '#/components/schemas/AutomationId' - type: 'null' sequence: type: integer allOf: - exclusiveMinimum: 0 workspace_id: $ref: '#/components/schemas/WorkspaceId' principal_id: $ref: '#/components/schemas/Union_280' anonymous_subject_ref: $ref: '#/components/schemas/Union_281' recorded_at: $ref: '#/components/schemas/UsageTimestamp' measurement: $ref: '#/components/schemas/SandboxComputeInterval' cost: type: object properties: tokens: false active_ms: type: integer allOf: - minimum: 0 storage_mib_ms: false running_ms: false billed_microusd: false required: - active_ms additionalProperties: false required: - id - session_id - run - attempt - agent_definition_id - sequence - workspace_id - principal_id - anonymous_subject_ref - recorded_at - measurement - cost additionalProperties: false - type: object properties: id: $ref: '#/components/schemas/UsageEntryId' session_id: $ref: '#/components/schemas/SessionId' run: $ref: '#/components/schemas/RunId' attempt: $ref: '#/components/schemas/RunAttemptId' agent_definition_id: $ref: '#/components/schemas/AgentId' surface_scope_id: anyOf: - $ref: '#/components/schemas/SurfaceScopeId' - type: 'null' automation_id: anyOf: - $ref: '#/components/schemas/AutomationId' - type: 'null' sequence: type: integer allOf: - exclusiveMinimum: 0 workspace_id: $ref: '#/components/schemas/WorkspaceId' principal_id: $ref: '#/components/schemas/Union_280' anonymous_subject_ref: $ref: '#/components/schemas/Union_281' recorded_at: $ref: '#/components/schemas/UsageTimestamp' measurement: $ref: '#/components/schemas/SnapshotRetentionInterval' cost: type: object properties: tokens: false active_ms: false storage_mib_ms: type: integer allOf: - minimum: 0 running_ms: false billed_microusd: false required: - storage_mib_ms additionalProperties: false required: - id - session_id - run - attempt - agent_definition_id - sequence - workspace_id - principal_id - anonymous_subject_ref - recorded_at - measurement - cost additionalProperties: false - type: object properties: id: $ref: '#/components/schemas/UsageEntryId' session_id: $ref: '#/components/schemas/SessionId' run: $ref: '#/components/schemas/RunId' attempt: $ref: '#/components/schemas/RunAttemptId' agent_definition_id: $ref: '#/components/schemas/AgentId' surface_scope_id: anyOf: - $ref: '#/components/schemas/SurfaceScopeId' - type: 'null' automation_id: anyOf: - $ref: '#/components/schemas/AutomationId' - type: 'null' sequence: type: integer allOf: - exclusiveMinimum: 0 workspace_id: $ref: '#/components/schemas/WorkspaceId' principal_id: $ref: '#/components/schemas/Union_280' anonymous_subject_ref: $ref: '#/components/schemas/Union_281' recorded_at: $ref: '#/components/schemas/UsageTimestamp' measurement: $ref: '#/components/schemas/SessionRuntimeInterval' cost: type: object properties: tokens: false active_ms: false storage_mib_ms: false running_ms: type: integer allOf: - minimum: 0 billed_microusd: type: integer allOf: - minimum: 0 rounding_remainder_millionths: type: integer allOf: - minimum: 0 required: - running_ms - billed_microusd - rounding_remainder_millionths additionalProperties: false required: - id - session_id - run - attempt - agent_definition_id - sequence - workspace_id - principal_id - anonymous_subject_ref - recorded_at - measurement - cost additionalProperties: false WorkspaceId: type: string allOf: - pattern: ^wrkspc_[0-9a-f]{32}$ ValidationMalformedError: type: object properties: error: type: object properties: type: type: string enum: - validation.malformed message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#validation-malformed description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: >- The request could not be decoded or violated a declared input constraint. PolicyDeniedError: type: object properties: error: type: object properties: type: type: string enum: - policy.denied message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#policy-denied description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: Deployment governance or retention policy denied the request. RuntimeInternalError: type: object properties: error: type: object properties: type: type: string enum: - runtime.internal message: type: string more: type: string enum: - https://docs.checkfu.com/reference/errors#runtime-internal description: Stable public documentation and remedy for this error type. required: - type - message - more additionalProperties: false required: - error additionalProperties: false description: >- An unexpected internal failure occurred; the message contains an opaque incident reference. UsageEntryId: type: string allOf: - pattern: ^use_[0-9a-f]{32}$ RunAttemptId: type: string allOf: - pattern: ^ratt_[0-9a-f]{32}$ Union_280: anyOf: - $ref: '#/components/schemas/PrincipalId' - type: 'null' Union_281: anyOf: - type: string allOf: - minLength: 1 - type: 'null' UsageTimestamp: type: string allOf: - maxLength: 24 - pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$ description: A canonical UTC ISO-8601 usage timestamp with millisecond precision. ModelRoutingProfileId: type: string allOf: - pattern: ^mrp_[0-9a-f]{32}$ Objects_163: type: object properties: tier: $ref: '#/components/schemas/Union_129' provider: type: string allOf: - pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$ model: type: string allOf: - minLength: 1 - maxLength: 255 effort: type: string enum: - minimal - low - medium - high - max speed: type: string enum: - standard - fast required: - tier - provider - model additionalProperties: false Objects_73: type: object properties: input_tokens: type: integer allOf: - minimum: 0 cached_input_tokens: type: integer allOf: - minimum: 0 cache_write_input_tokens: type: integer allOf: - minimum: 0 output_tokens: type: integer allOf: - minimum: 0 reasoning_output_tokens: type: integer allOf: - minimum: 0 total_tokens: type: integer allOf: - minimum: 0 required: - input_tokens - cached_input_tokens - cache_write_input_tokens - output_tokens - reasoning_output_tokens - total_tokens additionalProperties: false Union_282: type: string enum: - platform_supply - byok - unknown Objects_164: type: object properties: unit: $ref: '#/components/schemas/Union_283' quantity_millionths: type: integer allOf: - minimum: 0 required: - unit - quantity_millionths additionalProperties: false Union_283: type: string enum: - image - video_second - compute_second SandboxComputeInterval: type: object properties: kind: type: string enum: - sandbox_compute provider: type: string allOf: - minLength: 1 sandbox_profile_id: $ref: '#/components/schemas/SandboxProfileId' period_started_at: $ref: '#/components/schemas/UsageTimestamp' period_ended_at: $ref: '#/components/schemas/UsageTimestamp' active_ms: type: integer allOf: - minimum: 0 required: - kind - provider - sandbox_profile_id - period_started_at - period_ended_at - active_ms additionalProperties: false SnapshotRetentionInterval: type: object properties: kind: type: string enum: - snapshot_retention checkpoint_id: $ref: '#/components/schemas/CheckpointId' provider: type: string allOf: - minLength: 1 sandbox_profile_id: $ref: '#/components/schemas/SandboxProfileId' storage_mib: type: integer allOf: - exclusiveMinimum: 0 period_started_at: $ref: '#/components/schemas/UsageTimestamp' period_ended_at: $ref: '#/components/schemas/UsageTimestamp' retained_ms: type: integer allOf: - minimum: 0 required: - kind - checkpoint_id - provider - sandbox_profile_id - storage_mib - period_started_at - period_ended_at - retained_ms additionalProperties: false SessionRuntimeInterval: type: object properties: kind: type: string enum: - session_runtime thread_id: anyOf: - $ref: '#/components/schemas/SessionThreadId' - type: 'null' placement: type: string enum: - hosted_sandbox - runner period_started_at: $ref: '#/components/schemas/UsageTimestamp' period_ended_at: $ref: '#/components/schemas/UsageTimestamp' running_ms: type: integer allOf: - minimum: 0 required: - kind - thread_id - placement - period_started_at - period_ended_at - running_ms additionalProperties: false Union_129: type: string enum: - default - planning - tool_loop SandboxProfileId: type: string allOf: - pattern: ^sprof_[0-9a-f]{32}$ CheckpointId: type: string allOf: - pattern: ^ckpt_[0-9a-f]{32}$ SessionThreadId: type: string allOf: - pattern: ^sthr_[0-9a-f]{32}$ securitySchemes: bearerAuth: type: http scheme: bearer ````