---
title: "Retrieve Run Usage"
method: GET
path: "/api/v1/runs/{id}/usage"
tags: ["Run Outputs"]
---

# Retrieve Run Usage

`GET /api/v1/runs/{id}/usage`

Returns token counts and costs broken down by stage and model for a specific run.

## Path parameters

- `id` string, required

## Response `200`

Usage data

- RunUsage — Complete usage breakdown for a single run.
  - `stages` RunUsageStage[], required — Per-node usage breakdown. Each row sums usage and runtime across all visits of that node.
    - `stage` UsageStageRef, required — Reference to a workflow node in a usage stage row.
      - `id` string, required — Stage identifier (slug).
      - `name` string, required — Human-readable stage name.
    - `model` UsageModelRef, required — Provider-qualified model identity a usage is grouped under. Carries the requested speed tier because providers price tiers differently.
      - `provider` string, required — LLM provider identifier.
      - `model_id` string, required
      - `speed` 'fast' | 'balanced' | 'economical' — lithos `Speed`: the requested latency or cost tier.
    - `usage` Usage, required — lithos `Usage`: token counts and, when known, what they cost. `cost` is absent when there is no cost data, never zero. A sum has a cost only when every part that used tokens was priced; its `source` is the parts' shared source, or `application` when they differ.
      - `tokens` TokenCounts, required — lithos `TokenCounts`: five disjoint token buckets. Every token is counted in exactly one, so their plain sum is the total. `input` excludes cache reads and writes, while `output` excludes reasoning tokens when the provider reports them separately. A bucket that is absent reads as zero.
        - `input` integer — Prompt tokens that were neither read from nor written to a cache.
        - `output` integer — Completion tokens that are not reasoning tokens.
        - `reasoning` integer — Completion tokens spent on reasoning, priced at the output rate.
        - `cache_read` integer — Prompt tokens served from a provider cache.
        - `cache_write` integer — Prompt tokens written into a provider cache.
      - `cost` Cost — lithos `Cost`: a USD amount in micros and where it came from.
        - `usd_micros` integer, required
        - `source` 'catalog' | 'provider' | 'application', required — Where a cost came from: `catalog` (estimated from catalog prices), `provider` (the provider's own reported cost), or `application` (a sum the caller assembled from differently sourced parts).
    - `timing` StageTiming, required — Timing breakdown for one stage visit. Fields are all milliseconds. `wall_time_ms` is elapsed clock time; `inference_time_ms` is Fabro- observed LLM request/stream elapsed time; `tool_time_ms` is tool or command execution elapsed time; `active_time_ms` equals `inference_time_ms + tool_time_ms`. For a terminal stage these come from the worker's own stopwatch and are authoritative. For a stage still in flight they are a live estimate reconstructed from the event log, and `active_time_ms` is clamped to `wall_time_ms`. The estimate is replaced by the authoritative breakdown when the stage reaches a terminal event.
      - `wall_time_ms` integer, required
      - `inference_time_ms` integer, required
      - `tool_time_ms` integer, required
      - `active_time_ms` integer, required — Equals `inference_time_ms + tool_time_ms`.
    - `started_at` string, date-time, nullable — Wall-clock time the latest attempt of this stage started, if known.
    - `state` 'pending' | 'running' | 'retrying' | 'succeeded' | 'partially_succeeded' | 'failed' | 'skipped' | 'cancelled' — Lifecycle projection state of a workflow stage.
  - `totals` RunUsageTotals, required — Aggregate usage totals across all stages of a run.
    - `timing` RunTiming, required — Timing rollup for an entire run. Active fields sum work across stage visits, so `active_time_ms` can exceed `wall_time_ms` when parallel branches run concurrently. For a running run, stages still in flight contribute a live estimate rather than nothing, so wall and active both advance continuously. Unlike `StageTiming`, active is not clamped to wall here — concurrent branches can legitimately sum past run wall time.
      - `wall_time_ms` integer, required
      - `inference_time_ms` integer, required
      - `tool_time_ms` integer, required
      - `active_time_ms` integer, required — Equals `inference_time_ms + tool_time_ms`.
    - `usage` Usage, required — lithos `Usage`: token counts and, when known, what they cost. `cost` is absent when there is no cost data, never zero. A sum has a cost only when every part that used tokens was priced; its `source` is the parts' shared source, or `application` when they differ.
      - `tokens` TokenCounts, required — lithos `TokenCounts`: five disjoint token buckets. Every token is counted in exactly one, so their plain sum is the total. `input` excludes cache reads and writes, while `output` excludes reasoning tokens when the provider reports them separately. A bucket that is absent reads as zero.
        - `input` integer — Prompt tokens that were neither read from nor written to a cache.
        - `output` integer — Completion tokens that are not reasoning tokens.
        - `reasoning` integer — Completion tokens spent on reasoning, priced at the output rate.
        - `cache_read` integer — Prompt tokens served from a provider cache.
        - `cache_write` integer — Prompt tokens written into a provider cache.
      - `cost` Cost — lithos `Cost`: a USD amount in micros and where it came from.
        - `usd_micros` integer, required
        - `source` 'catalog' | 'provider' | 'application', required — Where a cost came from: `catalog` (estimated from catalog prices), `provider` (the provider's own reported cost), or `application` (a sum the caller assembled from differently sourced parts).
  - `by_model` UsageByModel[], required — Usage grouped by model.
    - `model` UsageModelRef, required — Provider-qualified model identity a usage is grouped under. Carries the requested speed tier because providers price tiers differently.
      - `provider` string, required — LLM provider identifier.
      - `model_id` string, required
      - `speed` 'fast' | 'balanced' | 'economical' — lithos `Speed`: the requested latency or cost tier.
    - `stages` integer, required — Number of usage-bearing stage visits that used this model.
    - `usage` Usage, required — lithos `Usage`: token counts and, when known, what they cost. `cost` is absent when there is no cost data, never zero. A sum has a cost only when every part that used tokens was priced; its `source` is the parts' shared source, or `application` when they differ.
      - `tokens` TokenCounts, required — lithos `TokenCounts`: five disjoint token buckets. Every token is counted in exactly one, so their plain sum is the total. `input` excludes cache reads and writes, while `output` excludes reasoning tokens when the provider reports them separately. A bucket that is absent reads as zero.
        - `input` integer — Prompt tokens that were neither read from nor written to a cache.
        - `output` integer — Completion tokens that are not reasoning tokens.
        - `reasoning` integer — Completion tokens spent on reasoning, priced at the output rate.
        - `cache_read` integer — Prompt tokens served from a provider cache.
        - `cache_write` integer — Prompt tokens written into a provider cache.
      - `cost` Cost — lithos `Cost`: a USD amount in micros and where it came from.
        - `usd_micros` integer, required
        - `source` 'catalog' | 'provider' | 'application', required — Where a cost came from: `catalog` (estimated from catalog prices), `provider` (the provider's own reported cost), or `application` (a sum the caller assembled from differently sourced parts).

## Other responses

- `404` — Run not found

## Changes

- **2026-09-19** `efc644ab09d4` — 1 info
  - added the optional property `errors/items/meta` to the response with the `404` status
- **2026-09-14** `57ca921cdd38` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/fabro-sh/apis/fabro-run-api/changes/api/v1/runs/:id/usage/get.md)

---

[API](https://skmtc.dev/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.dev/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fabro-sh/apis/fabro-run-api/revisions/b760ef95cb3a?raw)