---
title: "Upload Usage"
method: POST
path: "/api/v1/usage"
---

# Upload Usage

`POST /api/v1/usage`

## Request

- Base URL: `https://api.stacktrace.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.stacktrace.ai/api/v1/usage`
- Auth: none declared

Accept one page of one agent's token usage, or its heartbeat (ADR-0077).

A sibling of `/detect-runs`: usage never travels on the detection document,
and neither upload gates the other (`stacktrace` ADR-0100).

## Headers

- `authorization` string, nullable

## Request body

- UsageUpload: One page of one agent's token usage, or a heartbeat with none.
  - `asset_id` string, required
  - `agent_kind` string, required
  - `agent_instance_id` string, nullable
  - `store_id` string, uuid, nullable
  - `stacktrace_version` string, required
  - `sent_at` string, date-time, required
  - `reported_through` string, date-time, nullable
  - `covered_from` string, date-time, nullable
  - `runs` UsageRunPayload[]
    - `run_id` string, required
    - `surface` 'chatgpt-work', nullable
    - `repo` string, nullable
    - `branch` string, nullable
    - `title` string, nullable
    - `account` string, nullable
    - `revision` integer, required
  - `buckets` UsageBucketPayload[]
    - `run_id` string, required
    - `session_id` string, required
    - `model` string, nullable
    - `start` string, date-time, required
    - `grain` 'minute' | 'hour', required
    - `input` integer, required
    - `output` integer, required
    - `cache_read` integer, required
    - `cache_write` integer, required
    - `cache_write_1h` integer
    - `revision` integer, required
  - `run_figures` UsageRunFiguresPayload[]
    - `run_id` string, required
    - `repo` string, nullable
    - `entrypoint` string, nullable
    - `model` string, nullable
    - `last_activity_at` string, date-time, required
    - `tokens` integer, required
    - `curve` integer[], required
    - `burn` integer[], required
    - `subagents_in_10m` integer, required
    - `repeats` integer, required
    - `input_per_response` integer, required
    - `lowest_cache_share` number, nullable
    - `cache_rewrites` integer, required
    - `revision` integer, required
  - `components` UsageComponentPayload[]
    - `run_id` string, required
    - `session_id` string, required
    - `kind` 'skill' | 'mcp_server' | 'builtin' | 'label', required
    - `name` string, required
    - `model` string, nullable
    - `day` string, date, required
    - `tokens_per_call` integer, required
    - `calls` integer, required
    - `used` boolean, required
    - `result_tokens` integer
    - `result_calls` integer
    - `revision` integer, required
  - `accounts` AccountCardPayload[]
    - `account` string, required
    - `person_key` string, nullable
    - `display_name` string, nullable
    - `name_from` 'account' | 'email', nullable
    - `plan` string, nullable
    - `seen_at` string, date-time, required

## Response `201`

Successful Response

- UsageResponse
  - `runs_accepted` integer, required
  - `buckets_accepted` integer, required
  - `figures_accepted` integer
  - `components_accepted` integer

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/stacktrace/apis/stacktrace-fleet-api.md) - [All operations](https://skmtc.dev/stacktrace/apis/stacktrace-fleet-api/llms.txt) - [OpenAPI document](https://skmtc.dev/stacktrace/apis/stacktrace-fleet-api/revisions/0ee5484d1d0b?raw)