docs(drift): draft from internal source

[pedromcunha]

Drafted from an internal source repo, requested by @ipeleg.

This PR was auto-generated by the reusable-docs-draft-pr workflow from a Claude-drafted update in the source repo. It is opened as a draft — please review, edit as needed, and mark ready for review before merging.

Review checklist

• Content matches the behavior shipped in the source PR
• No internal-only details (service names, file paths, unreleased names, security internals) leaked into the draft
• Conforms to CLAUDE.md style rules
• Cross-references and internal links resolve
• Any Needs human input items from the source comment are addressed

---

Generated by reusable-docs-draft-pr.yml in relayprotocol/agents-config.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
unevenlabs	🟢 Ready	View Preview	Oct 13, 2026, 12:27 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

Claude finished @ipeleg's task in 37s —— View job

---

Code review

The change is small: one new changelog entry and a new frontmatter description on get-usage.mdx. The changelog heading matches the ## YYYY-MM-DD — <summary> shape that scripts/build-changelog.mjs parses, the **Added** leads are correct, the entry is newest-first, and the /references/api/api-keys link resolves. Nothing blocks the merge. A few things are worth checking first.

1. x-dev-portal-key appears in public docs for the first time. Search the box below.
x-dev-portal-key shows up in no other page in this repo. Its only appearances are the new get-usage.mdx description (line 3) and the changelog entry. The PR checklist asks for "no internal-only details … security internals". Please confirm that this header is a supported, public auth method and is in the OpenAPI spec for GET /metrics/usage. If it isn't public, drop it from both files. I couldn't fetch the spec from this runner to check.

2. The changelog explains things no page documents.
The entry says "the durable identity for an integration" and introduces x-dev-portal-key auth. Then it links to API keys and Rate Limits. That page says nothing about Apps, appId, usage metrics, or x-dev-portal-key. Readers who follow the link won't find the context they need. Either:

• link to /references/api/get-usage instead (the OpenAPI-rendered page is where these params and fields live), or
• add a short section on Apps and x-dev-portal-key to api-keys.mdx, under "Tracking requests". Flag it for human review.

Fix this →

3. The endpoint isn't linked. Other recent entries link the endpoint on first mention, for example [`GET /balance/{wallet}/events`](/references/api/get-balance-events). This entry leaves GET /metrics/usage as plain code. Linking it to /references/api/get-usage follows §2.6 and fixes #2 at the same time.

4. The get-usage.mdx description breaks the frontmatter rule. §2.1 / §3.3 ask for a terse, one-sentence description. The new one is two sentences and has a header name without backticks. A shorter version:

description: "Get API call counts grouped by API key, endpoint, status code, and error code"

Leave the auth-mode details to the OpenAPI body.

5. Content worth checking against the source PR (not style issues):

• The "including inactive keys" claim. The entry says the appId filter resolves "every current credential under an App — including inactive keys". The /requests/v3 entry from 2026-10-06 says revoked keys are included because attribution is indexed at request time. Here, attribution is resolved at read time, and hard-deleted credentials drop out. Please confirm "inactive" means revoked-but-not-deleted, and consider saying so outright.
• Matching rules differ from /requests/v3. On /metrics/usage, appId is OR-matched with apiKey/apiKeyId. On /requests/v3 it's ANDed. That's fine if it's intentional, but readers will compare the two entries, so a short note on the difference would help.
• Retention windows. "24h minutely, 7d hourly, 14d daily" isn't documented anywhere else in the repo. Please check it against the shipped behavior.
• 403 for a plain x-api-key. Please confirm that a plain x-api-key gets 403, not 400, when it passes appId.

Minor: The first **Added** paragraph is about 8 sentences long. That matches the long entries already in this file, so I'm not asking for a change. It is well past the 2–3 sentence guideline in §2.10, though.

No changes pushed. This was a review only.

[greptile-apps]

Confidence Score: 4/5

[Low impact] Updates API documentation for usage metrics.

This PR appears safe to merge, with a non-blocking readability improvement in the changelog.

Findings

1.  Important constraints get buried ▶

Summary

This PR documents App-scoped usage for GET /metrics/usage.

• Usage reports can now filter by Apps and show each row’s App ID.

_{Reviews (1) · Last reviewed commit: "docs(drift): draft from internal source" · Reviewed by Greptile}

[greptile-apps]

Important constraints get buried

The new filter paragraph packs six sentences into one block, making the authentication requirement, shared limit, and error responses hard to find. The response paragraph also exceeds the style guide’s three-sentence limit. Split these into shorter paragraphs or bullets so readers can quickly find the constraints.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!