query_metrics
Aggregate cost, latency, token usage, and score values from Langfuse for analytics by defining metrics, dimensions, filters, and time range.
Instructions
Query aggregated metrics (cost, latency, token usage, counts, score values) from Langfuse.
Wraps the Langfuse v2 metrics endpoint. Use this for analytics questions — "what did
inference cost in the last 24h grouped by model", "p95 latency per prompt", "score
distribution by name" — instead of pulling raw observations and aggregating client-side.
Per-parameter contracts live in the Field descriptions above.
Notes:
- The v2 metrics endpoint is Langfuse Cloud-only; self-hosted instances may return 404.
- Recently-ingested data can lag (OTEL ingestion delay up to ~10 minutes).
- High-cardinality fields (id, traceId, userId, sessionId) must be filters, not dimensions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| age | No | Minutes to look back from now (e.g. 1440 for 24h). Used when from_timestamp is omitted; defaults to 1440 (24h) when no time range is given. | |
| view | Yes | Data view to aggregate over: 'observations' (spans/generations/events — latency, cost, tokens, counts), 'scores-numeric' (numeric/boolean scores), or 'scores-categorical' (categorical scores). Call get_metrics_schema for the full dimension/measure catalog per view. | |
| filters | No | Optional filter objects: {'column','operator','value','type', plus 'key' for metadata/object types}. Example: [{'column':'userId','operator':'=','value':'u1','type':'string'}]. See get_metrics_schema for operators and types. | |
| metrics | Yes | One or more metrics to compute. Each item is {'measure': <name>, 'aggregation': <fn>}, e.g. [{'measure': 'totalCost', 'aggregation': 'sum'}, {'measure': 'latency', 'aggregation': 'p95'}]. Aggregations: sum, avg, count, max, min, p50, p75, p90, p95, p99, histogram. | |
| order_by | No | Optional ordering: list of {'field': <dimension-or-metric>, 'direction': 'asc'|'desc'}. | |
| dimensions | No | Optional fields to group results by, e.g. ['providedModelName']. Do NOT use high-cardinality fields (id, traceId, userId, sessionId) as dimensions — pass them as filters instead. | |
| output_mode | No | Controls the output format and action. 'compact' (default): Returns a summarized JSON object optimized for direct agent consumption. 'full_json_string': Returns the complete, raw JSON data serialized as a string. 'full_json_file': Returns a summarized JSON object AND saves the complete data to a file. | compact |
| to_timestamp | No | ISO-8601 end of the time range. Defaults to now (UTC). | |
| from_timestamp | No | ISO-8601 start of the time range. Overrides 'age' when provided. | |
| time_granularity | No | When set, results are bucketed by this granularity across the time range (time series). |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |