aggregate_calls
Aggregate LLM call data by provider, model, time period, tag, or error, computing metrics like cost, latency, tokens, count, and error rate.
Instructions
Get an aggregation cube over calls (POST /v1/query/aggregate). groupBy (provider / model / day / hour / minute / tag / error) x metric (cost / latency / tokens / input_tokens / output_tokens / cached_tokens / cache_savings / count / error_rate) — e.g. "aggregate this month's cost by model" in one call. tag mode requires tagKey (alphanumerics plus _ - only, e.g. 'env' / 'feature'). error mode aggregates only error rows by error string (which errors, how many; metric=count recommended). hour mode caps at 168h / minute mode at 60min (400 beyond). cost = SUM(cost_usd) / latency = AVG(latency_ms) / tokens = SUM(total_tokens) / input_tokens = SUM(prompt_tokens) / output_tokens = SUM(completion_tokens) / cached_tokens = SUM(cached_read_tokens) / cache_savings = SUM(cache_savings_usd) / count = COUNT(*) / error_rate = errors / total. Returns { groups: [{key, value, count}], total: {value, count} }.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| metric | No | Metric kind ('cost' / 'latency' / 'tokens' / 'input_tokens' / 'output_tokens' / 'cached_tokens' / 'cache_savings' / 'reasoning_tokens' / 'audio_tokens' / 'ttft' / 'count' / 'error_rate'), default = 'cost'. cached_tokens = SUM(cached_read_tokens), cache_savings = SUM(cache_savings_usd) (prompt-cache savings), reasoning_tokens = SUM(reasoning tokens), audio_tokens = SUM(audio tokens), ttft = AVG(ms to first token) | cost |
| tagKey | No | Required when groupBy='tag'. Key name inside the tags JSON (alphanumerics plus _- only, 1-64 chars) | |
| endTime | No | Range end ISO timestamp (UTC; omit = now) | |
| groupBy | No | Aggregation axis ('provider' / 'model' / 'day' / 'hour' / 'minute' / 'tag' / 'error'), default = 'provider'. hour caps at 168h / minute at 60min. error aggregates only error rows by kind | provider |
| provider | No | Provider filter ('openai' / 'anthropic' etc.); omit = all providers | |
| startTime | No | Range start ISO timestamp (UTC; omit = all time) |