usage_summary
Summarize LLM usage and costs for a chosen period (today, week, month, year). Returns totals, top providers and models by cost, and the most expensive call. Optionally include failed requests.
Instructions
Return a one-shot summary of usage over a named calendar period.
period is one of today | week | month | year (default: "week").
Boundaries are calendar UTC: today = since 00:00 UTC today,
week = since Monday 00:00 UTC, month = since the 1st of the
month, year = since January 1st. Returns totals, the top-3
providers and top-3 models by cost (with pct of total), and the
single most expensive call in the window — or largest_call=None
when the window is empty.
include_failed defaults to False: totals, top-N rollups, and
largest_call all exclude success=False rows (partial-stream
captures and other failure rows). Pass True for symmetric
debugging access to the failure population.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | week | |
| include_failed | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| period | Yes | ||
| call_count | Yes | ||
| top_models | Yes | ||
| largest_call | Yes | ||
| top_providers | Yes | ||
| total_cost_usd | Yes |