A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Amplitude API is how an app or AI agent works with a product analytics project: sending events, querying analytics such as segmentation, funnels, and retention, exporting the raw event stream, and managing cohorts and the event taxonomy. Access is granted through a per-project API key, often paired with a secret key, and that credential is all-or-nothing for the project rather than scoped to a specific action. Amplitude does not pin one shared API version, and each area is addressed and evolves on its own path.
How an app or AI agent connects to Amplitude determines what it can reach. There is a route for sending events, a route for querying analytics and managing the data taxonomy, and a hosted server that exposes Amplitude tools to agents, and each is governed by the credential behind it.
The ingestion endpoints take JSON event payloads at https://api2.amplitude.com (api.eu.amplitude.com for the EU region) and return a status. A call authenticates with the project API key placed in the request body. HTTP V2 handles real-time uploads, the batch endpoint handles higher volume, and identify and groupidentify update user and group properties.
The query, export, cohort, and taxonomy APIs answer at https://amplitude.com (analytics.eu.amplitude.com for the EU region), except the User Profile API at https://profile-api.amplitude.com. Most authenticate with HTTP Basic auth using the project API key and secret key. The User Profile API instead uses an Authorization: Api-Key header carrying the secret key.
A hosted Model Context Protocol server at https://mcp.amplitude.com/mcp (https://mcp.eu.amplitude.com/mcp for the EU region) exposes Amplitude tools to AI agents. It authenticates with OAuth 2.0 and respects the signed-in user's existing Amplitude permissions, so an agent reaches only the projects and data that user can see. Tools cover ad-hoc segmentation, funnels, and retention, reading and editing charts, dashboards, notebooks, experiments, cohorts, and metrics, taxonomy management, and Session Replay search. It is not an event-ingestion endpoint.
The ingestion endpoints authenticate with the project API key alone, passed in the request body. The key identifies which project events land in, and it is enough on its own to write events and property updates. It does not read analytics or raw data.
The analytics, export, cohort, and taxonomy APIs authenticate with the project API key as the username and the secret key as the password, over HTTP Basic auth. The pair is scoped to one project and carries no per-endpoint permissions, so any holder can call every endpoint in that project, including raw user-level export.
The User Profile API authenticates with the project secret key in an Authorization: Api-Key header, rather than Basic auth. It reads one user's computed profile at low latency and is not available in the EU data region.
The MCP server uses OAuth 2.0 with Amplitude, so an agent acts as a signed-in user and inherits that user's existing project and data permissions rather than holding a static key.
The Amplitude API is split into areas an agent can act on, like sending events, querying analytics such as segmentation, funnels, and retention, exporting raw data, managing cohorts, and editing the event taxonomy. Each area has its own credential and its own reach, and some return raw user-level data.
Send events into a project and update user and group properties.
Query computed analytics like active users, segmentation, funnels, retention, and revenue.
Find a user and read a single user's event history and profile.
Export the raw event stream for a time range as zipped JSON.
List cohorts, download a cohort's membership, and upload or update a cohort.
Define and manage event types, event properties, and user properties in the tracking plan.
Read a single user's computed profile, properties, recommendations, and cohort membership at low latency.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Event ingestionSend events into a project and update user and group properties.4 | ||||||
| POST | /2/httpapi | Upload one or more events into a project in real time. | write | — | Current | |
Authenticates with the project API key in the request body; one of user_id or device_id and event_type are required. Host api2.amplitude.com (api.eu.amplitude.com for EU). Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitThrottles a device or user over ~30 events/second average; 429 when exceeded. SourceOfficial documentation ↗ | ||||||
| POST | /batch | Upload a large batch of events in a single request, for higher-volume server-side ingestion. | write | — | Current | |
Same project API key in the body as HTTP V2; accepts up to 2,000 events and a 20 MB payload, with higher per-device throughput than HTTP V2. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitUp to 1,000 events/second per device or user ID; 500,000 events per rolling 24 hours per device or user. SourceOfficial documentation ↗ | ||||||
| POST | /identify | Set or update user properties without sending an event. | write | — | Current | |
Project API key in the body. Host api2.amplitude.com (api.eu.amplitude.com for EU). Acts onuser property Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitAn individual user is limited to 1,800 user-property updates per hour. SourceOfficial documentation ↗ | ||||||
| POST | /groupidentify | Set or update group properties, which appear as segments in the dashboard. | write | — | Current | |
Project API key in the body. Updates affect only subsequent events, not historical data. Host api2.amplitude.com. Acts ongroup property Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Analytics (Dashboard REST)Query computed analytics like active users, segmentation, funnels, retention, and revenue.8 | ||||||
| GET | /api/2/users | Get active and new user counts over a date range, with optional segmentation. | read | — | Current | |
Basic auth with API key and secret. Host amplitude.com (analytics.eu.amplitude.com for EU). Draws from the hourly cost budget. Acts onactive users Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2/events/list | List every event type in the project with weekly totals. | read | — | Current | |
Basic auth with API key and secret. Acts onevent type Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2/events/segmentation | Get metrics for an event over time, broken down by a property. | read | — | Current | |
Basic auth with API key and secret. Query cost is the number of events plus 4 per group-by. Acts onsegmentation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCost: number of events + 4 per group-by, against the 108,000-per-hour budget. SourceOfficial documentation ↗ | ||||||
| GET | /api/2/funnels | Get conversion and drop-off rates through an ordered sequence of events. | read | — | Current | |
Basic auth with API key and secret. Query cost is (number of events x 2) plus 4 per group-by. Acts onfunnel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCost: (number of events x 2) + 4 per group-by. SourceOfficial documentation ↗ | ||||||
| GET | /api/2/retention | Get retention, how many users return over time after a starting action. | read | — | Current | |
Basic auth with API key and secret. Query cost is a flat 8. Acts onretention Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCost: 8 per query. SourceOfficial documentation ↗ | ||||||
| GET | /api/2/realtime | Get active user counts at 5-minute granularity for the last two days. | read | — | Current | |
Basic auth with API key and secret. Acts onactive users Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2/revenue/ltv | Get the lifetime value of new users over a date range. | read | — | Current | |
Basic auth with API key and secret. Acts onrevenue Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/3/chart/{chart_id}/csv | Export the data behind a saved chart as CSV. | read | — | Current | |
Basic auth with API key and secret. Acts onchart Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
User lookupFind a user and read a single user's event history and profile.2 | ||||||
| GET | /api/2/usersearch | Find a user by Amplitude ID, user ID, device ID, or user property. | read | — | Current | |
Basic auth with API key and secret. User Activity and Search allow 10 concurrent requests rather than the default 5. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/2/useractivity | Get a single user's summary and recent event history. | read | — | Current | |
Basic auth with API key and secret. Returns individual user-level events. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Raw data exportExport the raw event stream for a time range as zipped JSON.1 | ||||||
| GET | /api/2/export | Export the raw event stream for an hour range as a zipped archive of JSON files. | read | — | Current | |
Basic auth with API key and secret. start and end are hours in YYYYMMDDTHH; up to 365 days per call and a 4 GB size limit, returning 400 if exceeded. Host amplitude.com. Acts onevent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Behavioral cohortsList cohorts, download a cohort's membership, and upload or update a cohort.4 | ||||||
| GET | /api/3/cohorts | List all discoverable cohorts for a project. | read | — | Current | |
Basic auth with API key and secret. Acts oncohort Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCohort endpoints allow 60 requests per 10 minutes per project, 4 in parallel. SourceOfficial documentation ↗ | ||||||
| GET | /api/5/cohorts/request/{id} | Request a cohort's membership, which starts an asynchronous download job. | read | — | Current | |
Basic auth with API key and secret. Returns a request_id to poll, then download. A cohort can hold up to 2 million users. Acts oncohort Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/cohorts/upload | Create a new cohort or replace an existing cohort by uploading a list of IDs. | write | — | Current | |
Basic auth with API key and secret. Acts oncohort Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/3/cohorts/membership | Add or remove IDs to update an existing cohort's membership incrementally. | write | — | Current | |
Basic auth with API key and secret. Acts oncohort Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TaxonomyDefine and manage event types, event properties, and user properties in the tracking plan.5 | ||||||
| GET | /api/2/taxonomy/event | List all event types defined in the project's tracking plan. | read | — | Current | |
Basic auth with API key and secret. A GET costs 1 against the taxonomy budget. Acts onevent type Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitGET cost 1; period budget 7,200 per hour, 4 concurrent. SourceOfficial documentation ↗ | ||||||
| POST | /api/2/taxonomy/event | Create an event type in the tracking plan. | write | — | Current | |
Basic auth with API key and secret. A POST costs 2 against the taxonomy budget. Acts onevent type Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPOST cost 2. SourceOfficial documentation ↗ | ||||||
| PUT | /api/2/taxonomy/event/:event_type | Update an existing event type in the tracking plan. | write | — | Current | |
Basic auth with API key and secret. A PUT costs 2 against the taxonomy budget. Acts onevent type Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPUT cost 2. SourceOfficial documentation ↗ | ||||||
| GET | /api/2/taxonomy/event-property | List event properties defined in the tracking plan. | read | — | Current | |
Basic auth with API key and secret. Acts onevent property Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitGET cost 1. SourceOfficial documentation ↗ | ||||||
| POST | /api/2/taxonomy/user-property | Create a user property in the tracking plan. | write | — | Current | |
Basic auth with API key and secret. A POST costs 2 against the taxonomy budget. Acts onuser property Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitPOST cost 2. SourceOfficial documentation ↗ | ||||||
User ProfileRead a single user's computed profile, properties, recommendations, and cohort membership at low latency.1 | ||||||
| GET | /v1/userprofile | Get a single user's computed profile, properties, recommendations, computations, and cohort membership at low latency. | read | — | Current | |
Authenticates with the project secret key in an 'Authorization: Api-Key Acts onuser profile Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitAn org is limited to 600 requests per minute across all endpoints. SourceOfficial documentation ↗ | ||||||
Amplitude does not publish a standard outbound webhook in these APIs. Its ingestion endpoints are request and response only, so an integration sends events and reads back a status rather than receiving pushed notifications.
| Event | What it signals | Triggered by |
|---|
Amplitude limits ingestion by throughput per device or user, and limits the analytics and export APIs by a cost model where each query draws from an hourly budget and a small number of queries can run at once.
Amplitude limits ingestion and queries with two different models. Ingestion is throttled per device or user: HTTP V2 averages about 30 events per second for a single device or user and returns 429 over that, the batch endpoint allows up to 1,000 events per second and 500,000 per rolling 24 hours per device or user, and a user is capped at 1,800 property updates per hour. The analytics Dashboard REST API uses a cost budget instead: 108,000 cost units per hour with at most 5 concurrent queries, 10 for User Activity and Search, where each query's cost is days times conditions times a per-query-type cost, so event segmentation costs the number of events plus 4 per group-by, funnels cost the number of events times 2 plus 4 per group-by, and retention costs 8. The taxonomy API has its own budget of 7,200 cost per hour with 4 concurrent, and the cohort API allows 60 requests per 10 minutes per project. The User Profile API allows 600 requests per minute across an org.
The analytics APIs return a computed result set for the requested window rather than paging through rows, so the date range and the chosen interval bound the response. The Export API is bounded by time instead of pages: a single call covers at most 365 days and 4 GB, and a larger pull is split into smaller windows. The cohort download is asynchronous: a request returns a request_id that is polled until the file is ready to download.
HTTP V2 requests must stay under 1 MB with fewer than 2,000 events, and the batch endpoint allows up to 20 MB and 2,000 events, returning 413 when exceeded. Within a payload a string value may be up to 1,024 characters and nested objects may not exceed 40 layers. The Export API returns at most 4 GB per call, returning 400 above that, and exported data is available within about 2 hours of ingestion. A cohort can hold up to 2 million users.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Invalid request | The request was malformed: bad JSON, a missing required field, an invalid field value, or a request that exceeds a documented limit such as the Export API's 4 GB cap. | Read the error body, correct the payload or narrow the query, and resend. |
| 403 | Forbidden | The request was blocked, for example by Amplitude's web application firewall or because it came from a sanctioned region. | Confirm the credential and the source of the request, and contact Amplitude if a legitimate request is blocked. |
| 404 | Not Found | There is no data for the requested window, for example an Export API call over an empty time range. | Confirm the time range holds data and that ingestion has had time to process it. |
| 413 | Payload Too Large | The request body exceeds the size limit, 1 MB for HTTP V2 and 20 MB for the batch endpoint. | Split the events across smaller requests and resend. |
| 429 | Too Many Requests | A throughput limit was hit for a device or user on ingestion, or a query exceeded the analytics cost budget or concurrency limit. | Back off and retry with exponential backoff, smooth the request rate, and dedupe events with insert_id. |
| 500 | Server Error | Amplitude encountered an error handling the request, which can also appear as 502 or 504. | Retry with backoff, and use insert_id so a retry does not duplicate events. |
| 503 | Service Unavailable | The request failed because of an internal Amplitude issue. | Retry with backoff once the service recovers. |
Amplitude does not date or pin a single API version. Each API is addressed by its own path, and the path segment carries the version of that specific endpoint.
Amplitude does not publish one dated, account-wide API version. Each API is addressed by its own path, and the version segment in that path belongs to the specific endpoint: ingestion at /2/httpapi, /batch, /identify, and /groupidentify; the Dashboard REST API at /api/2; cohorts spanning /api/3 and /api/5; taxonomy at /api/2/taxonomy; and the User Profile API at /v1/userprofile. An integration pins to the documented path for the endpoint it uses, and the APIs evolve independently rather than on one shared version timeline.
Each API moves independently; pin to the documented path for the endpoint in use.
Amplitude API docs ↗Bollard AI sits between a team's AI agents and Amplitude. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.