Record a single LLM/agent run and return the stored row.

Cost is taken from cost_usd when provided; otherwise it is computed from the built-in pricing table (USD per 1M tokens) when the model is known. If the model is unpriced and no cost is given, cost is stored as null and the response notes that the model is unpriced so you can extend the table.

Return the full stored row for a single run id.

List runs newest-first with optional filters.

Filters: model, agent, status ('ok'/'error'), tag (matches any run carrying that tag), and since (ISO timestamp or relative window like '24h', '7d'). Use limit/offset to page. Returns up to limit rows plus the total count matching the filters so you know whether to page further.

Aggregate telemetry into cost and reliability rollups.

group_by is one of: 'model', 'agent', 'finish_reason', 'day', or 'tag'. Optional since limits the window (ISO timestamp or relative like '30d'). Each group reports run count, total input/output tokens, total cost, average latency, and error rate. Groups are sorted by total cost descending.

Export raw runs as a JSON array or CSV string for external analysis.

fmt is 'json' or 'csv'. Optional since limits the window. Newest-first, capped at limit rows (max 10000).

Delete a single run by id. Requires confirm=true to actually remove it.

This is the only destructive tool. It scopes to one id and refuses to run without an explicit confirm, so it cannot wipe the store by accident.