Amplitude's API reference is broad and individually well-written, but the two event-ingestion endpoints publish contradictory per-device rate limits, the page literally titled "API Authentication" never documents the auth scheme, and several reference pages state limits without quantifying them or export as broken content in the AI corpus.
1. The two event-ingestion APIs give contradictory per-device rate limits (critical)
Location: /docs/apis/analytics/http-v2 and /docs/apis/analytics/batch-event-upload
Problem: Both endpoints ingest events keyed by device/user ID, but they publish different per-device throughput limits. HTTP V2's 429 section states Amplitude "throttles requests for users and devices that exceed 30 events per second." Batch states: "Each API key can send up to 1000 events per second for any individual device ID or user ID. If you exceed that rate, the API rejects the upload and returns a 429 response." Both numbers describe the same scope — per individual device/user — yet they are ~33× apart. Compounding this, HTTP V2 never reconciles or scopes its own two figures: its "Upload limit" section tells Starter customers "the 1000 events per second limit still applies" (presented as an overall upload ceiling), while its 429 section sets a 30-events-per-second per-device throttle, and the page never states the scope of either number (per project? per key? per device?). A reader cannot tell whether these coexist or conflict.
Consequence: A developer (or an AI agent) tuning a retry/backoff loop has no reliable number for the per-device limit. Code sized for 1000 events/sec per device against HTTP V2 will silently hit 429s and drop events; code throttled to 30 events/sec against Batch wastes ~97% of available throughput. Agents can't apply human judgment to reconcile the two pages — they pick one number and fail silently.
The fix: State the per-device/user limit once, in a shared table, with the scope spelled out (per API key / per device / per project) for each ingestion endpoint. On the HTTP V2 page, explicitly distinguish the overall upload ceiling from the per-device throttle so the 1000 and 30 figures stop reading as a contradiction.
2. The "API Authentication" page never documents how to authenticate (critical)
Location: /docs/apis/authentication
Problem: The dedicated authentication page explains only how to find keys in the web UI ("select Manage next to API Key or Secret Key to view and copy each value"). It never documents the actual auth mechanism: that server-side APIs use HTTP Basic auth, the format, which APIs take the API key vs the Secret Key, or what the Authorization header looks like. The Basic-auth scheme appears only incidentally in another page's curl example (the Export API's ), and the only conceptual statement of it is buried on the Keys and Tokens page ("A Secret Key authenticates you to server-side APIs that read or modify project data"). Auth content is fragmented across three pages: this one, , and .
Code verification
Runtime snippet checks
Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.
Consequence: A developer who opens the page titled "API Authentication" to learn how to authenticate leaves without the answer. They must reverse-engineer the scheme from a curl example on an unrelated endpoint page, then guess whether other endpoints use the same scheme. This is the single most common first task against any API, and the canonical page punts on it.
The fix: Document the Basic-auth scheme on the Authentication page itself: the header format, an explicit Authorization: Basic <base64(api_key:secret_key)> / -u example, which key class each API expects, and key lifecycle (rotation/expiry). Link the three auth pages into a clear hierarchy.
3. Payload size limits conflict (1 MB vs 20 MB) and the Batch page's "differs in two ways" undersells the real differences (significant)
Location: /docs/apis/analytics/http-v2 and /docs/apis/analytics/batch-event-upload
Problem: HTTP V2 instructs Growth/Enterprise customers to "Keep request sizes under 1 MB with fewer than 2000 events per request" (413 otherwise). Batch caps the payload at "20MB in size." Yet the Batch page tells readers the API "differs from the HTTP API in two ways" and lists only (1) Content-type must be application/json and (2) the key is events plural — silently omitting the two differences that actually drive endpoint choice: a 20× larger payload ceiling and the per-device rate-limit difference from Finding 1.
Consequence: A developer reading "differs in two ways" will reasonably assume the size and throughput limits are identical and pick the wrong endpoint, then hit unexpected 413/429 errors at scale. The whole reason to reach for Batch — a larger payload ceiling — is exactly what the comparison hides.
The fix: Rewrite the "differs in two ways" section into a comparison table covering Content-type, payload key, max payload size (1 MB vs 20 MB), event-count cap, and per-device rate limit, so the trade-off that determines endpoint selection is explicit.
4. The SDK landing page leaks an internal CMS note in the AI corpus instead of the SDK catalog (significant)
Location: /docs/sdks (as exported in /docs/llms-full.txt)
Problem: In the official AI corpus, the entire body of the SDK landing page is replaced by an authoring note: "Page content is rendered by the sdk-catalog-landing template. Edit copy in lib/sdk-product-meta.ts." The live page renders the real catalog ("Amplitude SDKs are organized by the product they connect to — Analytics, Experiment, Session Replay, and Ampli…"), so this is an export defect in llms-full.txt, not a live-page defect — but it also leaks an internal implementation file path into a public artifact.
Consequence: An agent relying on llms-full.txt to enumerate Amplitude's SDKs gets a CMS editing instruction instead of the SDK list, so it can't tell a developer which SDKs exist. The leaked lib/sdk-product-meta.ts path is needless internal detail in published content.
The fix: Fix the corpus generator so template-rendered pages export their rendered output (the catalog) rather than the template placeholder, and strip authoring notes and file paths from published content.
5. The JavaScript SDK install snippet renders empty in the AI corpus, with the </head> target stripped (significant)
Location: /docs/sdks/analytics/browser/javascript-sdk (as exported in /docs/llms-full.txt)
Problem: In the corpus, the inline </head> tag is stripped, leaving the instruction "paste the code snippet just before the `` tag" with empty backticks, and the install snippet itself renders as an empty ```html code block. The live page is correct (the </head> reference and full <script> snippet are present), so this is an llms-full.txt export defect affecting AI consumers.
Consequence: An agent helping a developer install the JavaScript SDK from the corpus gets an empty code block and an instruction missing its target element. It cannot produce a working snippet or say where to paste it — the core action of the page is unrecoverable from the AI artifact.
The fix: Fix the export pipeline so inline HTML tags (</head>) survive escaping and code-block contents are preserved; add a regression check that flags empty code fences in the generated corpus.
6. Browser SDK naming sprawl, with an inverted Experiment-support gotcha buried in a note (significant)
Location: /docs/sdks/analytics/browser/browser-unified-sdk and /docs/sdks/analytics/browser/javascript-sdk
Problem: To install "the browser SDK," a developer must reconcile at least five overlapping names: the Unified SDK (npm, @amplitude/unified), the Unified Script (CDN), the GTM Template, Browser SDK 2 (@amplitude/analytics-browser), and the legacy JavaScript SDK (now "a maintenance SDK and receives only bug fixes until deprecation"). The product-support matrix is also non-intuitively inverted: per the comparison table, the Unified Script (CDN) includes Web Experiment (@amplitude/experiment-tag) but not Feature Experiment, while the Unified SDK (npm) is the reverse — it includes Feature Experiment (@amplitude/experiment-js-client) but not Web Experiment. This inversion is explained only in a "note" callout.
Consequence: A developer who picks an install method assuming "Unified = everything" will silently lack the experimentation product they need (Web vs Feature Experiment) and won't discover it until flags or visual tests don't fire. The overlapping-name landscape also makes it hard to tell which install path is current versus in maintenance.
The fix: Lead the browser SDK section with a single decision table (name, package, status: recommended/maintenance) and promote the Web-vs-Feature-Experiment inversion to a prominent warning on the install-method comparison, not a note.
7. The Export API requires Basic auth but documents no authentication-failure response (significant)
Location: /docs/apis/analytics/export
Problem: The Export endpoint authenticates with Basic auth using the project Secret Key (its curl example uses -u {api_key}:{secret_key}, and Keys and Tokens confirms "A Secret Key authenticates you to server-side APIs that read or modify project data"). Yet the only error path the page's considerations describe is the 400 returned when an export exceeds the 4 GB size limit ("The size limit is 4GB. If the size exceeds 4GB, the request returns a 400 response"). There is no documented behavior for an authentication or authorization failure (401/403).
Consequence: The most common failure when integrating an authenticated API — wrong, missing, or wrong-type credentials — has no documented response or remedy on the reference page. A developer hitting an auth failure has nothing telling them it's a credentials problem versus a malformed request (400), so they burn time guessing. Combined with Finding 2 (auth itself is under-documented), the auth failure path is invisible end to end.
The fix: Document the authentication-failure responses (401, and 403 where role/permission applies) for the Export endpoint and every other endpoint that requires authentication, describing the cause (invalid key, wrong key type, insufficient role) and the remedy.
8. The Taxonomy API states it has limits but never gives the numbers (significant)
Location: /docs/apis/analytics/taxonomy
Problem: The Limits section reads, in full: "Each endpoint has a concurrent limit and a rate limit. The concurrent limit restricts how many requests you can run at the same time. The rate limit restricts the total number of queries per hour. Limits are per project." No actual figures are given for either the concurrent limit or the rate limit. This is in direct contrast to the Dashboard REST and Behavioral Cohorts pages, which publish exact numbers (5 concurrent across REST endpoints; 360 queries/hour for user activity/search; 500 cohort downloads/month).
Consequence: A developer cannot size a Taxonomy integration against limits that are named but never quantified. They must provision blindly and discover the real thresholds only by triggering 429s in production — and an AI agent has no number to back off against at all.
The fix: Publish the concurrent limit and the per-hour rate limit for the Taxonomy endpoints (per project), matching the level of detail already shown on the Dashboard REST and Behavioral Cohorts pages.
9. Endpoint host sprawl is patched per-page instead of documented once (minor)
Problem: Different APIs live on different hosts. The HTTP V2 page itself lists ingestion on api2.amplitude.com (EU api.eu.amplitude.com) and notes that "Other Amplitude APIs use different hostnames (for example api.amplitude.com, core.amplitude.com, data-api.amplitude.com, or experiment.amplitude.com)," while the Export API's default host is the bare https://amplitude.com with an EU host of analytics.eu.amplitude.com — a different EU pattern from ingestion. Multiple REST pages (HTTP V2, Export, Dashboard REST) repeat the same warning that analytics.amplitude.com is the web UI and must not be used for REST requests — evidence that this confusion recurs and is being patched page by page.
Consequence: Developers and agents must maintain a per-endpoint host map with no single source of truth, and the duplicated "don't use analytics.amplitude.com" warning shows people regularly send requests to the wrong host. EU customers are especially exposed because the EU host pattern differs between ingestion and Export.
The fix: Publish one canonical host/region table mapping every API to its default and EU base URL, link every reference page to it, and state the analytics.amplitude.com-is-not-an-API-host rule once there.
10. The "Retention metric deprecated" notice doesn't disambiguate from Retention analysis (minor)
Problem: A callout in the Experiment Results metric picker states flatly: "Amplitude has deprecated the Retention metric. It's no longer available." But "Retention" remains a first-class, documented concept elsewhere — the Dashboard REST API explicitly lists "Retention Analysis: The cost for this chart is 8." The notice doesn't clarify that it refers only to the single-use Retention metric type within Experiment Results, not Retention analysis in general.
Consequence: A developer who reads the bald "Retention… no longer available" notice may conclude Retention analysis is gone product-wide and stop building against the Retention Analysis chart or its Dashboard REST cost model — which are very much still supported.
The fix: Scope the notice: "The single-use Retention metric type in Experiment Results is deprecated. This does not affect Retention Analysis charts or the Retention Analysis cost in the Dashboard REST API."
11. Cross-reference links render as plain text on the Keys and Tokens page (minor)
Location: /docs/apis/keys-and-tokens
Problem: Inline cross-references render as plain text with no link target — e.g. "To view your project's API Key and Secret Key, refer to Authentication." This is the one page that actually enumerates the full key taxonomy (Project API Key, Project Secret Key, Experiment deployment/management keys, Data API Token, SCIM Key, org-level keys), yet its onward references dead-end as plain text and the API reference pages don't link to it consistently.
Consequence: The page that resolves "which key do I use where" is hard to reach, and its own references can't be followed, so developers can't navigate from a key mention to the taxonomy that explains it.
The fix: Restore the hyperlinks on these cross-references and link to the Keys and Tokens taxonomy from each API reference page's auth section.
12. The Taxonomy API surfaces an unexplained gp: prefix and an undocumented ordering constraint (minor)
Location: /docs/apis/analytics/taxonomy
Problem: The Taxonomy considerations note, in passing, that "In responses, custom user properties have a gp: prefix. For example, gp:my_custom_property," but never explain what gp: stands for, that it is a system-applied prefix, or that it appears in responses from other APIs too. The same section also states "You must plan events or properties in the schema before you can delete them through this API" — an ordering constraint stated only here.
Consequence: A developer or agent parsing API responses encounters property keys prefixed gp: with no definition of the term, and may treat the prefix as part of the property name (or strip it incorrectly). The plan-before-delete rule, documented only as a one-line aside, means delete calls fail for an unstated reason if the property was never planned.
The fix: Define the gp: prefix (what it denotes, where it appears) in a glossary or the response-format section referenced from every API that returns it, and document the plan-before-delete requirement as an explicit precondition on the delete endpoint, not a buried aside.
What they do well
Session definitions are consistent across surfaces — the Identify Users guide states web sessions time out after 30 minutes and mobile after 5 minutes of background inactivity, matching other surfaces. A good model for how the conflicting rate-limit numbers should be handled.
Behavioral Cohorts and Dashboard REST agree on the shared concurrency limit ("5 concurrent across all REST endpoints, including cohort download"), proving cross-page consistency is achievable here.
The Dashboard REST cost-per-query model is documented in real detail (explicit per-chart-type formulas), giving developers a precise way to predict rate-limit consumption.
Top 3 recommendations
Reconcile the ingestion limits in one shared table — the per-device rate limit (30 vs 1000 events/sec) and the payload ceiling (1 MB vs 20 MB) — with the scope of each number spelled out, so HTTP V2 and Batch stop contradicting each other.
Turn the Authentication page into an actual auth reference — document the Basic-auth scheme, header format, per-API key requirements, and authentication-failure responses (401/403), and centralize the host/region map the reference pages depend on.
Quantify the limits you only describe, and fix the AI-corpus exports — publish the Taxonomy concurrent/rate limits, and repair the llms-full.txt defects (the CMS-note leak and the empty code blocks) so agents consuming Amplitude's own corpus get usable content.