Authenticate all requests using HTTP Basic Authentication with your Amplitude API key as the username and your secret key as the password.
List available cohorts with GET https://amplitude.com/api/3/cohorts to identify the cohort ID and confirm its size — cohorts over 2 million users cannot be exported via this API and require a cohort sync instead.
Initiate the async export by sending GET https://amplitude.com/api/5/cohorts/request/{cohort_id}; optionally append ?props=1 to include all user properties or ?propKeys=email,plan to include specific ones. The response returns a request_id.
Poll the job status with GET https://amplitude.com/api/5/cohorts/request-status/{request_id} until async_status returns JOB COMPLETED (HTTP 200); a still-running job returns HTTP 202 with JOB INPROGRESS.
Download the cohort file with GET https://amplitude.com/api/5/cohorts/request/{request_id}/file — small cohorts return data inline; large cohorts redirect (HTTP 302) to a pre-signed S3 URL that expires after one minute, so download immediately.
Known gotchas
The Behavioral Cohorts Download API is limited to 500 requests per month on Growth and Enterprise plans — check current usage via GET /api/3/cohorts/usage before running automated exports.
The S3 pre-signed download URL is valid for only one minute; however, the API request link itself is valid for seven days, allowing you to re-request a fresh S3 link if the first expires.
For EU data residency projects, use https://analytics.eu.amplitude.com as the base URL instead of https://amplitude.com — using the wrong region returns authentication or data-not-found errors.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp