---
title: "Get raw third-party harness usage"
method: GET
path: "/agent/runs/{runId}/harness-usage"
tags: ["Agents"]
---

# Get raw third-party harness usage

`GET /agent/runs/{runId}/harness-usage`

## Request

- Base URL: `https://app.warp.dev/api/v1`
- URL: `https://app.warp.dev/api/v1/agent/runs/{runId}/harness-usage`
- Auth: HTTP bearer

Return the latest cumulative raw usage snapshot retained for a
Claude Code or Codex run. Missing metrics are represented as an
unavailable result rather than zero. Access uses the same run view
authorization as transcript reads.

## Path parameters

- `runId` string, required

## Response `200`

Raw harness usage or an unavailable result

- GetRunHarnessUsageResponse
  - `run_id` string, required
  - `conversation_id` string, required
  - `available` boolean, required
  - `age_seconds` integer, nullable
  - `usage` union
    - ClaudeHarnessUsageEnvelope
      - `metricsVersion` 1, required: Server-owned storage format metadata, not the producer's parser version.
      - `harness` 'CLAUDE_CODE', required
      - `executionId` integer, required
      - `captureSequence` integer, required
      - `capturedAt` string, date-time, required
      - `snapshot` object, required
        - `coverage` RetainedHarnessUsageCoverage, required
          - `tokenStatus` 'known' | 'partial' | 'unavailable', required
          - `toolStatus` 'known' | 'partial' | 'unavailable', required
        - `payload` ClaudeHarnessUsagePayload, required
          - `usage` ClaudeTokenUsage, nullable: Native cumulative token categories; cache counters are not added to input_tokens.
            - `input_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
            - `output_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
            - `cache_read_input_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
            - `cache_creation_input_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
            - `cache_creation` ClaudeCacheCreationUsage, nullable
              - …
          - `attribution` ClaudeAttributedUsage[], nullable
            - `model` string, nullable
            - `service_tier` string, nullable
            - `inference_geo` string, nullable
            - `speed` string, nullable
            - `usage` ClaudeTokenUsage, nullable, required: Native cumulative token categories; cache counters are not added to input_tokens.
              - …
          - `toolCalls` HarnessToolCalls, nullable: Native tool invocation counts. Total must equal the sum of byName; tool names are arbitrary map keys.
            - `total` integer, required
            - `byName` object, required
    - CodexHarnessUsageEnvelope
      - `metricsVersion` 1, required: Server-owned storage format metadata, not the producer's parser version.
      - `harness` 'CODEX', required
      - `executionId` integer, required
      - `captureSequence` integer, required
      - `capturedAt` string, date-time, required
      - `snapshot` object, required
        - `coverage` RetainedHarnessUsageCoverage, required
          - `tokenStatus` 'known' | 'partial' | 'unavailable', required
          - `toolStatus` 'known' | 'partial' | 'unavailable', required
        - `payload` CodexHarnessUsagePayload, required
          - `usage` CodexTokenUsage, nullable: Native checkpoint counters. Cached input and reasoning output may overlap other categories; no derived total is inferred.
            - `input_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
            - `cached_input_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
            - `cache_write_input_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
            - `output_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
            - `reasoning_output_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
            - `total_tokens` integer, nullable: A native count. Absent or null means unmeasured, not zero.
          - `attribution` CodexAttributedUsage[], nullable
            - `model` string, nullable
            - `service_tier` string, nullable
            - `inference_geo` string, nullable
            - `speed` string, nullable
            - `usage` CodexTokenUsage, nullable, required: Native checkpoint counters. Cached input and reasoning output may overlap other categories; no derived total is inferred.
              - …
          - `toolCalls` HarnessToolCalls, nullable: Native tool invocation counts. Total must equal the sum of byName; tool names are arbitrary map keys.
            - `total` integer, required
            - `byName` object, required

## Other responses

- `401`: Authentication required
- `403`: No permission to view the run
- `404`: Run not found or has no linked conversation
- `500`: Internal server error

## Changes

- **2026-10-13** `96d1e59a65c5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/warp/apis/oz-agent-api/changes/agent/runs/:runId/harness-usage/get.md)

---

[API](https://skmtc.dev/warp/apis/oz-agent-api.md) - [All operations](https://skmtc.dev/warp/apis/oz-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/warp/apis/oz-agent-api/revisions/4b5d145669be?raw)