docs: make Metrics API v2 the default

[AkioNuernberger]

What changed

• Made Metrics API v2 the canonical Metrics API documentation, with availability shown directly below the page title.
• Removed the duplicate v2 heading and endpoint while preserving data availability, deprecated API, migration, and key-change guidance.
• Updated inbound links to the former #v2 section so they point to the canonical page.
• Regenerated the Metrics API cookbook from its updated notebook source.

Why

Metrics API v2 is the standard API. Readers now encounter its availability and core endpoint immediately, without navigating a duplicate subsection.

Validation

• pnpm run format:check
• node scripts/check-h1-headings.js
• pnpm run link-check against a local docs server
• Verified no remaining internal links target metrics-api#v2

Greptile Summary

The PR promotes Metrics API v2 to the canonical Metrics API page, surfaces availability near the title, and updates links and generated cookbook content accordingly.

• Removes the duplicate v2 section and reorganizes migration guidance.
• Retargets links from the former #v2 section to the canonical page.
• Regenerates the Metrics API v2 cookbook from its notebook source.
• Leaves a small compatibility issue for previously published #v2 fragment URLs.

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking inbound-link compatibility issue around the removed #v2 fragment.

The canonical documentation and cookbook remain internally consistent, but two existing changelog links and external bookmarks can still request a fragment that the updated page no longer defines.

Files Needing Attention: content/docs/metrics/features/metrics-api.mdx

Prompt To Fix All With AI

### Issue 1
content/docs/metrics/features/metrics-api.mdx:11-19
**Removed v2 compatibility anchor**

The canonical-page restructuring removes the published `#v2` fragment, while existing changelog links and external bookmarks still target it. Those links now land at the page top instead of resolving their intended anchor, so preserve an element with `id="v2"` when removing the duplicate section.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "Merge branch 'main' into agent/consolida..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used (3)

• Knowledge Base — Content and MDX Build Pipeline
• Knowledge Base — Cookbook and Integrations Pipeline
• Knowledge Base — Product Documentation Content (content/docs, content/guides, content/faq)

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
langfuse-docs	Ready	Preview	Aug 5, 2026 5:02pm

[AkioNuernberger]

@Lotte-Verheyden pls review in case I missed something

[greptile-apps]

Removed v2 compatibility anchor

The canonical-page restructuring removes the published #v2 fragment, while existing changelog links and external bookmarks still target it. Those links now land at the page top instead of resolving their intended anchor, so preserve an element with id="v2" when removing the duplicate section.

Knowledge Base Used:

• Content and MDX Build Pipeline
• Product Documentation Content (content/docs, content/guides, content/faq)

Prompt To Fix With AI

This is a comment left during a code review.
Path: content/docs/metrics/features/metrics-api.mdx
Line: 11-19

Comment:
**Removed v2 compatibility anchor**

The canonical-page restructuring removes the published `#v2` fragment, while existing changelog links and external bookmarks still target it. Those links now land at the page top instead of resolving their intended anchor, so preserve an element with `id="v2"` when removing the duplicate section.

**Knowledge Base Used:**
- [Content and MDX Build Pipeline](https://app.greptile.com/personal-org-4986/-/custom-context/knowledge-base/langfuse/langfuse-docs/-/docs/content-mdx-pipeline.md)
- [Product Documentation Content (content/docs, content/guides, content/faq)](https://app.greptile.com/personal-org-4986/-/custom-context/knowledge-base/langfuse/langfuse-docs/-/docs/product-docs-content.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[claude]

I didn't find any additional bugs beyond the inline nit. This is a size:L PR touching 17 files with a real content restructure (removing the '## Metrics API v2' heading and merging it into the intro) plus mechanical link updates, so it's worth a human pass alongside the nit already flagged.

Extended reasoning...

Overview

This PR consolidates the Metrics API docs page so 'v2' becomes the default/canonical framing rather than a separate subsection, and updates ~15 other files (blog, changelog, FAQ, other docs, cookbook, pricing table, md-override) to drop the now-removed #v2 anchor from links pointing at the Metrics API page. The core content edit is in content/docs/metrics/features/metrics-api.mdx: the ## Metrics API v2 [#v2] heading and its intro/endpoint block were removed, with the AvailabilityBanner and endpoint moved up under the H1, and the six reference H3s (Available Views, Key Changes, Row Limit, High Cardinality, Ordering, Example) were reordered slightly and kept.

Security risks

None. This is a documentation-only change (MDX/Markdown content, a notebook regenerated from source, and one pricing table href/react component prop). No code paths, auth, or data handling are touched.

Level of scrutiny

Correctness-of-content review is the right bar here, not a code-logic review. I verified: (1) the #v2 anchor removed from the Metrics API page has no other stale inbound links from this PR's file set — a legacy /docs/analytics/metrics-api#v2 reference in an old 2025-12-17 changelog entry is unrelated and pre-existing; (2) the Observations API page's own #v2 anchor was correctly left untouched since that page's heading wasn't restructured, so links to observations-api#v2 remain valid; (3) md-override/pricing-self-host.md was updated in lockstep with PricingTable.tsx's href change, keeping the override in sync per repo convention.

Other factors

The one issue found (heading semantics: the six reference H3s now nest under the unrelated 'What you can do' H2 instead of a dedicated parent) is a nit — CI-passing, no broken links or rendering issues, just a sidebar/TOC organization quirk. Given the PR's size (17 files, size:L label) and that it includes a genuine content restructure rather than purely mechanical link swaps, and the author has already asked for a second human reviewer, I think a human look is warranted rather than a shadow-approval.

[claude]

🟡 The PR removes the '## Metrics API v2 [#v2]' H2 that used to parent the reference sections (Available Views in v2, Key Changes from v1, Row Limit, High Cardinality Dimensions, Ordering by metrics, Example), so those H3s now nest directly under the unrelated '## What you can do' H2 since no other H2 follows it. This is a docs table-of-contents/organization issue, not a build or rendering break — consider adding a dedicated H2 (e.g. a 'Reference' heading) to re-parent these sections.

Extended reasoning...

What happens: Before this PR, had the heading chain # Metrics API → ## What you can do → ## Metrics API v2 [#v2] → six ### reference subsections (Available Views in v2, Key Changes from v1, Row Limit, High Cardinality Dimensions, Ordering by metrics, Example). The PR intentionally merges the 'v2' framing into the page intro and deletes the ## Metrics API v2 [#v2] heading, but does not add a replacement H2 for the six H3 sections it used to own. Since the file has no other H2 after ## What you can do, all six H3s now nest directly beneath it in the document tree.

Why it's not caught by CI: check-h1-headings.js only counts H1 occurrences, and the resulting structure (H1 → H2 → H3, no skipped levels) is syntactically valid Markdown, so and the build both pass cleanly. This is a semantic/organizational issue, not a structural or lint violation.

Concrete proof — walk the file top to bottom:

1. Line 9: (H1)
2. Line 28: (H2) — a short bulleted list of capabilities (aggregate cost/tokens, group by dimensions, filter, power dashboards)
3. Line 49: (H3, child of 'What you can do')
4. Line 58: (H3, child of 'What you can do')
5. Line 68: (H3, child of 'What you can do')
6. Line 72: (H3, child of 'What you can do')
7. Line 76: (H3, child of 'What you can do')
8. Line 80: (H3, child of 'What you can do')

Rendered in the sidebar/table-of-contents, a reader sees 'Row Limit', 'High Cardinality Dimensions', and 'Example' listed as sub-items of 'What you can do', even though they document response/query constraints of the endpoint as a whole, unrelated to the 'what you can do' bullet list above them.

Impact: Purely navigational/organizational — no content is lost, no link breaks, and the page still reads fine linearly. The only effect is that the generated TOC/sidebar nesting is now misleading, which could make it slightly harder for readers scanning the sidebar to find 'Row Limit' or 'Example' since they'd expect to find them at a higher level or under a heading like 'Reference' or 'Query details'.

Suggested fix: Reintroduce a dedicated H2 (e.g. or ) directly above to re-parent the six sections, without reintroducing the removed 'v2' framing or duplicate endpoint block.

All three independent verifiers reached the same conclusion and rated this a nit: valid heading nesting, CI-passing, but a real semantic mis-parenting worth a follow-up cleanup rather than a blocking issue.