Langfuse Metrics

Prefer one bounded GET /api/public/v2/metrics query over downloading and aggregating observations. Metrics queries return aggregates and avoid exposing prompt or output content.

Use scripts/query-metrics-v2.mjs:

node .codex/skills/langfuse-metrics/scripts/query-metrics-v2.mjs summary --from 2026-08-26T00:00:00Z --model-prefix gpt-5.6-
node .codex/skills/langfuse-metrics/scripts/query-metrics-v2.mjs cost-report --from 2026-08-26T00:00:00Z --to 2026-08-27T00:00:00Z --completed-meetings 12 --transcribed-minutes 347
node .codex/skills/langfuse-metrics/scripts/query-metrics-v2.mjs query --file query.json

The helper reads LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and optional LANGFUSE_BASE_URL (Chronote defaults to the US cloud host). summary makes a single request grouped by provided model and observation name, returning count, total cost, average latency, and p95 latency. Use --dry-run to inspect the query without sending it. --model-prefix is sent as a Metrics v2 starts with filter so matching happens before the server's 1,000-row limit.

cost-report uses that same single aggregate query to return attributed cost, cost by model and feature, known fully-unpriced model groups, and group-based cost coverage. Pass PostHog's completed-meeting count and the application's transcribed-minute denominator when available to add unit costs. Do not call the coverage ratio exact: a group with some cost may still contain individual unpriced observations. Keep any unpriced TTS, image, or provider activity visible rather than estimating dollars from unrelated units.

Keep queries bounded with explicit UTC fromTimestamp and toTimestamp. Start with the dimensions and metrics needed to answer the question; do not add time buckets or high row limits speculatively. Metrics API v2 supports at most 1,000 rows and does not permit grouping by high-cardinality identifiers such as trace, session, or user IDs.

Before interpreting an empty result as no traffic, check ingestion freshness. Data from Langfuse Python SDK versions before 4.7 or JS/TS versions before 5.4 can appear in v2 endpoints up to 15 minutes late.

If row-level investigation is necessary, use GET /api/public/v2/observations with bounded fromStartTime and toStartTime, selective fields, and cursor pagination. Do not use deprecated /api/public/observations or page-based pagination. Omit the io field group unless the task genuinely requires user content and that access is authorized.

On HTTP 429, honor Retry-After. The helper retries once only when the wait is 60 seconds or less; otherwise it stops and reports the wait. Do not work around an organization-wide quota by rotating project keys. Langfuse applies rate limits to organization-level resource buckets shared by its projects and keys.

Aggregate health does not prove output quality. Report routing/configuration, traffic, latency, cost, and error evidence separately from representative workload or human quality validation. This skill is read-only and does not authorize prompt, model-routing, evaluator, or production configuration writes.

Current official references:

• https://langfuse.com/docs/metrics/features/metrics-api
• https://langfuse.com/guides/cookbook/example_metrics_api_v2
• https://langfuse.com/docs/api-and-data-platform/features/observations-api