Guide users to v2 data APIs

[maxdeichmann]

Summary

• Fold the v2 upgrade path into the resource-specific docs instead of keeping a standalone migration page.
• Make Observations API v2 and Metrics API v2 the default adoption path across the API & Data Platform overview, Public API, SDK query docs, Observations API docs, Metrics API docs, and the 524 FAQ.
• Keep older trace, observation, and metrics read APIs available in the docs, but describe them as not recommended for new extraction workflows because they are less performant at scale.

Why

Users should be guided toward the more performant v2 APIs for new data extraction workflows while existing older API integrations remain available. First-time users now land directly on Observations API v2 for row-level data or Metrics API v2 for aggregates. Existing SDK/API users get upgrade notes in the pages where they already look for the relevant resource.

Validation

• git diff --check passed.
• pnpm dlx prettier@3.8.3 --experimental-cli --check ... passed for the touched docs files.
• PR CI passed: format, check_h1, build-and-check-links, check-sitemap-links, Vercel, CodeQL, bundle analysis, and all-checks-pass.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview, Comment	May 19, 2026 9:28pm

[github-actions]

@claude review

[claude]

Substantive prior review feedback has been addressed across all six files; only a trivial duplicate-code-block nit remains.

Extended reasoning...

Overview

Docs-only PR steering users from v1 trace/observation/metrics read APIs to the v2 data APIs across six files: observations-api.mdx, metrics-api.mdx, public-api.mdx, query-via-sdk.mdx, the API & Data Platform overview, and the 524 FAQ. No code, no schema, no auth changes.

Security risks

None. This is documentation content — no runtime behavior, no secrets, no auth surfaces.

Level of scrutiny

Lower than usual for a doc-only PR, but I applied close scrutiny here because the new headline migration table is copy-pasteable URL guidance — incorrect parameter names would lead to silent data truncation in production billing/dashboard workflows. That motivated my prior review rounds.

Other factors

The author has substantively addressed every major prior concern across multiple commits:

• The upgrade table now uses fromStartTime/toStartTime for v2 observations (was the headline 🔴 bug).
• The v1→v2 metrics migration bullets now explicitly flag that userId/sessionId are filter-only on v2 (🔴), that rowLimit defaults to 100 (🟡), and that observation-view metrics have different semantics than trace-view ones (🔴).
• Cross-cutting pages (public-api.mdx, overview.mdx) now disclose the Cloud-only restriction (🔴).
• The SDK callout in query-via-sdk.mdx is back to type="warning" and explicitly notes the v2 aliases were removed in Python SDK v4 / JS/TS SDK v5 (🟡).
• The Python SDK link in public-api.mdx is reverted to /docs/sdk/python/sdk-v3 (🟡).
• The trace-level field gap is now called out in the observations-api upgrade section pointing users to Metrics API v2 with view: observations (🟡).
• Both v2 pages now say data 'can be delayed by up to 10 minutes' (🟡).

The only outstanding finding is a cosmetic nit (duplicate GET /api/public/v2/metrics code block in metrics-api.mdx), which is non-blocking and can be cleaned up in a follow-up. CI is green and the Vercel deployment is ready. Approving.