Model usage and cost for agents

Read input, output, and cached tokens, latency, and cost for your agent's model calls: per step, per trace, and totalled by model, provider, service, or step name.

Where usage comes from

Usage comes from the generation spans your runtime sends: provider, model, input_tokens, output_tokens, cached_input_tokens, and optionally reported_cost_usd. Flowyn does not call your model provider to measure it.

How cost is calculated

cost.status	Meaning
reported	You sent `reported_cost_usd`; Flowyn uses it.
estimated	Calculated from the reported tokens and Flowyn's price catalog.
pending	The span is still running.
unavailable	Cannot be calculated; `reason` says why, such as `model_unknown`.

The price catalog covers selected OpenAI, Anthropic, and Google models, each price with the date it took effect. Unknown cost is never shown as zero. Reported costs are observed values; stored estimates retain their pricing provenance. Neither is a guaranteed provider invoice.

Read usage

bash

curl https://api.flowyn.dev/v1/agent-telemetry/usage?last=7d&group_by=model&bucket=day \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Parameter	Values
agent_id	Optional scoped Agent UUID; attribution follows the trace root
last	`1h`, `24h` (default), `7d`, `14d`, `30d`
group_by	`model`, `provider`, `service`, `name` (up to 50 groups)
bucket	`hour` or `day`, at most 720 time-series points

The totals include generations, failed generations, input, cached input, output, and total tokens, generations missing usage, average and p95 duration, and cost split into reported and estimated amounts.

Per-Agent advisory warnings

Set token_warning_24h to a positive integer (at most 9,007,199,254,740,991) and cost_warning_24h_usd to a positive decimal string (at most 1,000,000 USD with at most 9 fractional digits) on Agent create or PATCH. Null disables the respective warning. PATCH requires the current expected_revision and an Idempotency-Key: an omitted threshold is preserved; explicit null clears it.

curl -X PATCH https://api.flowyn.dev/v1/agents/7d0f6c1e-2b1a-4c55-9f53-1a2b3c4d5e6f \
  -H "Authorization: Bearer $FLOWYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: agent-warnings-001" \
  -d '{
    "expected_revision": 1,
    "token_warning_24h": 100000,
    "cost_warning_24h_usd": "2.50"
  }'

bash

curl https://api.flowyn.dev/v1/agent-telemetry/usage?agent_id=7d0f6c1e-2b1a-4c55-9f53-1a2b3c4d5e6f&last=24h&group_by=model&bucket=hour \
  -H "Authorization: Bearer $FLOWYN_API_KEY"

Per-Agent attribution follows the scoped trace root. Child generation spans count even when they omit agent_id; rootless or unlinked traces are excluded and disclosed. The report uses the bounded interval [from, evaluated_at) and excludes future spans. Reported cost takes precedence over the stored estimate, while missing token usage and unpriced contributions remain visible.

Warnings are computed only when requested, from the same view of data and configuration. The 24-hour response includes thresholds, Agent revision, evaluated_at, observed totals, and warning states. A warning is reached when observed usage is greater than or equal to its threshold. Other supported windows provide analysis only. This is observation and advice: no remaining balance, safe-to-spend amount, provider spending guarantee, or external-runtime enforcement.

Per trace

GET /v1/agent-telemetry/{trace_id} returns the same totals for one trace under usage, and each model step carries its own cost and time_to_first_token_ms when completion_started_at was sent.

In the dashboard

Traces → Model usage shows the same totals and groups.

Next step

Human approvals.