query_metrics
Query aggregated Langfuse metrics for cost, latency, token usage, counts, and scores, using filters, dimensions, and time granularity to answer analytics questions without client-side aggregation.
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 |