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

# Retrieve Run Billing

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

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

## Path parameters

- `id` string, required

## Response `200`

Billing data

- RunBilling — Complete billing breakdown for a single run.
  - `stages` RunBillingStage[], required — Per-node billing breakdown. Each row sums billing and runtime across all visits of that node.
    - `stage` BillingStageRef, required — Reference to a workflow node in a billing stage row.
      - `id` string, required — Stage identifier (slug).
      - `name` string, required — Human-readable stage name.
    - `model` BillingModelRef, required — Provider-qualified billing model identity used for cost estimates.
      - `provider` string, required — LLM provider identifier.
      - `model_id` string, required
      - `speed` 'standard' | 'fast' — Optional provider-specific model speed tier used for cost estimates.
    - `billing` BilledTokenCounts, required — Token counts with optional billed USD micros totals.
      - `input_tokens` integer, required — Number of input tokens consumed.
      - `output_tokens` integer, required — Number of output tokens generated.
      - `total_tokens` integer, required — Total billable tokens aggregated across categories.
      - `reasoning_tokens` integer, required — Number of reasoning tokens.
      - `cache_read_tokens` integer, required — Number of cache read tokens.
      - `cache_write_tokens` integer, required — Number of cache write tokens.
      - `total_usd_micros` integer, nullable — Billed USD amount in micros.
    - `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` RunBillingTotals, required — Aggregate billing 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`.
    - `input_tokens` integer, required — Total input tokens consumed.
    - `output_tokens` integer, required — Total output tokens generated.
    - `total_tokens` integer, required — Total tokens aggregated across all billing categories.
    - `reasoning_tokens` integer, required — Total reasoning tokens.
    - `cache_read_tokens` integer, required — Total cache read tokens.
    - `cache_write_tokens` integer, required — Total cache write tokens.
    - `total_usd_micros` integer, nullable — Total billed USD amount in micros.
  - `by_model` BillingByModel[], required — Billing grouped by model.
    - `model` BillingModelRef, required — Provider-qualified billing model identity used for cost estimates.
      - `provider` string, required — LLM provider identifier.
      - `model_id` string, required
      - `speed` 'standard' | 'fast' — Optional provider-specific model speed tier used for cost estimates.
    - `stages` integer, required — Number of usage-bearing stage visits that used this model.
    - `billing` BilledTokenCounts, required — Token counts with optional billed USD micros totals.
      - `input_tokens` integer, required — Number of input tokens consumed.
      - `output_tokens` integer, required — Number of output tokens generated.
      - `total_tokens` integer, required — Total billable tokens aggregated across categories.
      - `reasoning_tokens` integer, required — Number of reasoning tokens.
      - `cache_read_tokens` integer, required — Number of cache read tokens.
      - `cache_write_tokens` integer, required — Number of cache write tokens.
      - `total_usd_micros` integer, nullable — Billed USD amount in micros.

## Other responses

- `404` — Run not found

---

[API](https://skmtc.net/fabro-sh/apis/fabro-run-api.md) · [All operations](https://skmtc.net/fabro-sh/apis/fabro-run-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fabro-sh/fabro-run-api/versions/bee030053823/schema)