---
title: "Aggregate Usage"
method: GET
path: "/api/v1/usage"
tags: ["Usage"]
---

# Aggregate Usage

`GET /api/v1/usage`

Returns aggregate token counts and costs across all completed runs since server start.

## Response `200`

Aggregate usage data

- AggregateUsage — Aggregate token counts and costs across all runs since server start.
  - `totals` AggregateUsageTotals, required — Aggregate usage totals across all runs.
    - `runs` integer, required — Total number of completed runs.
    - `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` 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`.
  - `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).

## Changes

- **2026-09-14** `57ca921cdd38` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/fabro-sh/apis/fabro-run-api/changes/api/v1/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/1258a4cf33df?raw)