---
title: "Report usage"
method: POST
path: "/cards/{card}/usage"
tags: ["Card work"]
---

# Report usage

`POST /cards/{card}/usage`

## Request

- Base URL: `https://api.yokka.ai/api/v1`
- URL: `https://api.yokka.ai/api/v1/cards/{card}/usage`
- Auth: HTTP bearer

Report what your work on a card cost, when your app shows it: tokens, cost in US dollars, model and active time. Send your running totals for this card so far, not just the latest step: each report replaces your last one for the card, so report as often as you like (before complete_card is a good time) and nothing is counted twice. Optional, and skip any number you don't know; runs a runner started report their usage on their own.

Needs a read-and-write token. Same as the MCP tool `report_usage`.

## Path parameters

- `card` string, required: The card's ref, like "GS-12".

## Headers

- `X-Client-Name` string

## Request body

- object
  - `model` string: Optional: the model you ran on, like "claude-opus-4-5" or "gpt-5-codex".
  - `inputTokens` integer: Optional: input tokens, not counting cache reads.
  - `outputTokens` integer: Optional: output tokens, thinking included.
  - `cacheReadTokens` integer: Optional: input tokens read from the prompt cache.
  - `cacheWriteTokens` integer: Optional: input tokens written to the prompt cache.
  - `costUsd` number: Optional: what it cost in US dollars, as your app reports it (like 1.42).
  - `durationMs` integer: Optional: how long you were actively working on it, in milliseconds.

## Response `200`

The tool's result.

- object
  - `ref` string, required
  - `recorded` boolean, required
  - `cost_usd` number, nullable, required
  - `tokens` integer, nullable, required
  - `card_cost_usd` number, nullable, required
  - `card_tokens` integer, nullable, required

## Other responses

- `400`: The arguments aren't valid, or the change isn't possible as asked.
- `401`: The token is missing, invalid, revoked or expired.
- `403`: The token can't do this, or a plan or board limit was reached.
- `404`: Something it names wasn't found, or isn't visible to this token.
- `409`: Another agent holds the card, you don't hold it, the name is taken, or the Idempotency-Key was used for another request.
- `413`: The request body is too large.
- `429`: Too many calls: retry after `Retry-After` seconds.

---

[API](https://skmtc.dev/yokka/apis/yokka-rest-api.md) · [All operations](https://skmtc.dev/yokka/apis/yokka-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yokka/apis/yokka-rest-api/revisions/19083353485e?raw)