update step by step guidance

[annabellscha]

Disclaimer: Experimental PR review

Greptile Summary

This PR expands the "Migration Notes" section of the v2 Metrics and Observations API changelog entry, replacing four high-level bullets with a detailed 5-step guide that covers endpoint prefixes, cursor pagination, selective field retrieval, new defaults/limits, and SDK/server version compatibility (including self-hosting guidance).
Adds a direct link from docs page to upgrade steps.

Confidence Score: 5/5

Safe to merge — documentation-only change with no logic errors or breaking content.

The PR is a pure documentation update that expands existing migration guidance with more detail. No code is changed, no APIs are modified, and the added content is accurate and consistent with the surrounding callout and feature description.

No files require special attention.

Important Files Changed

Filename	Overview
content/changelog/2025-12-17-v2-metrics-and-observations-api.mdx	Migration Notes section expanded from 4 simple bullets to a 5-step guide with sub-bullets covering URL prefixes, cursor pagination, field retrieval, defaults/limits, and SDK compatibility; no logic errors found.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Start Migration] --> B[Step 1: Update API prefix to /api/public/v2/]
    B --> C[Step 2: Switch to cursor-based pagination]
    C --> D[Step 3: Add selective field retrieval via 'fields' param]
    D --> E[Step 4: Review new defaults & limits]
    E --> F{Self-hosted?}
    F -- Yes --> G[Use legacy v1 namespaces for now]
    F -- No: Cloud --> H{SDK version?}
    H -- Python v4+ / JS-TS v5+ --> I[v2 is default under langfuse.api.observations / metrics]
    H -- Python ≥3.11.1 / JS-TS ≥4.5.1 --> J[Use transitional v2 namespaces]
    H -- Direct API call --> K[Call /v2 endpoint directly, no SDK change needed]

Loading

_{Reviews (1): Last reviewed commit: "update step by step guidance" | Re-trigger Greptile}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview, Comment	May 5, 2026 9:37am

[github-actions]

@claude review

[claude]

🔴 Step 3 of the migration notes shows two SDK examples (Python v3.x snake_case observations_v_2 and v4+/v5+ observations), but neither works for JS/TS v4.x users — and step 5 explicitly states JS/TS v4.5.1 is the minimum supported version. A JS/TS v4.5.1 reader copying line 73 (langfuse.api.observations_v_2) hits a TypeError because that namespace is Python-only snake_case (the JS/TS v4.x equivalent is camelCase langfuse.api.observationsV2), and copying line 74 silently calls the legacy v1 endpoint because langfuse.api.observations is v2 only in JS/TS v5+. Add a SDK (JS/TS v4.x): langfuse.api.observationsV2.list({ fields: "core,basic,usage" }) bullet, and rename the (v3.x) label to Python SDK v3.x to disambiguate.

Extended reasoning...

What the bug is

Step 3 of the migration notes (content/changelog/2025-12-17-v2-metrics-and-observations-api.mdx lines 73-74) lists two transitional SDK examples:

- SDK (v3.x): langfuse.api.observations_v_2.get_many(fields="core,basic,usage")
- SDK (v4+ Python / v5+ JS/TS): langfuse.api.observations.get_many(fields="core,basic,usage")

But step 5 (line 76) explicitly states the minimum compatible JS/TS SDK is v4.5.1 and adds: "In Python SDK v4+ and JS/TS SDK v5+, v2 is the default under langfuse.api.observations." That leaves the JS/TS v4.x audience — the stated minimum — without any working example.

Why neither example works on JS/TS v4.x

Verified against content/docs/observability/sdk/upgrade-path/js-v4-to-v5.mdx (lines 198-205), which is authoritative for the v4 → v5 namespace split:

v4 / transitional name	v5 name
langfuse.api.observationsV2	langfuse.api.observations
langfuse.api.observations (legacy v1)	langfuse.api.legacy.observationsV1

So in JS/TS v4.5.1:

• langfuse.api.observations_v_2 does not exist — that snake_case form is Python-only. Property access yields undefined, then .get_many throws TypeError: Cannot read properties of undefined. (Note also that get_many is Python naming; the JS API uses .list(...).)
• langfuse.api.observations is the legacy v1 namespace per the table above. A reader copying line 74 silently calls /api/public/observations (v1) instead of /api/public/v2/observations — exactly the silent-wrong-endpoint failure mode the migration notes are intended to prevent.

Step-by-step proof

1. A JS/TS user reads step 5 and pins the stated minimum: langfuse@4.5.1.
2. They scan step 3 for the matching SDK form. The (v3.x) bullet looks closest to their major series (4.x is older than 5+), so they try langfuse.api.observations_v_2.get_many({...}).
3. langfuse.api.observations_v_2 is undefined in JS/TS — the namespace is camelCase observationsV2. They get a runtime TypeError.
4. They retreat to the second bullet langfuse.api.observations.get_many(...). On v4.x this resolves to the legacy v1 resource, so the call hits /api/public/observations and silently returns v1 data — fields may be ignored.

Why existing wording doesn't prevent this

Step 5's note that langfuse.api.observations only points to v2 in Python v4+ / JS v5+ warns the reader, but step 3 provides no JS/TS v4.x alternative; the only "transitional" example uses Python-only snake_case syntax. This is the same class of issue as the prior resolved comment (which fixed the Python v3.x case) — the fix did not extend symmetrically to JS/TS v4.x.

How to fix

Add a third bullet under step 3 explicitly for JS/TS v4.x, and disambiguate the existing (v3.x) label:

- SDK (Python v3.x): langfuse.api.observations_v_2.get_many(fields="core,basic,usage")
- SDK (JS/TS v4.x): langfuse.api.observationsV2.list({ fields: "core,basic,usage" })
- SDK (Python v4+ / JS/TS v5+): langfuse.api.observations.get_many(fields="core,basic,usage")  // .list(...) in JS/TS

Impact

Documentation correctness for the migration audience the same step calls out. JS/TS v4.5.1 is what step 5 recommends users pin to, yet step 3 leaves them with no working example — a TypeError on one bullet and a silent v1 call on the other.