Amplitude Analytics connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Set up the connector

   Register your Amplitude Analytics credentials with Scalekit so it can authenticate requests on your behalf. You do this once per environment.

   Dashboard setup steps

   Register your Amplitude API Key and Secret Key with Scalekit so it can authenticate and proxy requests on behalf of your users. Amplitude uses HTTP Basic Auth — the API Key is the username and the Secret Key is the password. There is no redirect URI or OAuth flow.

   1. Find your Amplitude data residency region

      Amplitude runs two separate data residency regions with different credentials and API hosts. Before generating keys, confirm which region your project (or organization) lives in:

      Region	API host
      US (default)	amplitude.com
      EU	analytics.eu.amplitude.com

      Region must match your keys

      An API Key and Secret Key generated in one region will not authenticate against the other. Using the wrong region in Scalekit causes every request to fail.

   2. Get your API Key

      • Sign in to Amplitude and go to Settings → Agent Connectors (or API and Secret Keys) → API Keys.

      • Click Generate API Key, or copy an existing key’s value.

        

   3. Get your Secret Key

      • Click the Secret Keys tab.

      • Click Show next to the secret key that matches the API key you copied in step 2, and copy it.

        

      Project vs. organization credentials

      Most tools need project-level API Key and Secret Key. DSAR (data subject access request) tools need a separate connected account using organization-level credentials in the same fields. Use two different connected accounts if you need both.

   4. Create a connection in Scalekit

      • In the Scalekit dashboard, go to AgentKit → Connections → Create Connection.
      • Search for Amplitude Analytics and click Create.
      • Note the Connection name — use this as connection_name in your code (e.g., amplitudeanalytics).

   5. Add a connected account

      Connected accounts link a specific user identifier in your system to an Amplitude API Key, Secret Key, and region. Add them via the dashboard for testing, or via the Scalekit API in production.

      Via dashboard (for testing)

      • Open the connection and click the Connected Accounts tab → Add account.
      • Fill in Your User’s ID, API Key, Secret Key, and select the Data Residency Region that matches your keys.
      • Click Save.

      Via API (for production)

      Node.js

      // US region (default) — omit `domain` or set it to 'amplitude.com'
      await scalekit.connect.upsertConnectedAccount({
        connectionName: 'amplitudeanalytics',
        identifier: 'user@example.com',
        credentials: {
          username: 'your-amplitude-api-key',
          password: 'your-amplitude-secret-key',
          domain: 'amplitude.com',
        },
      })
      
      // EU region
      await scalekit.connect.upsertConnectedAccount({
        connectionName: 'amplitudeanalytics',
        identifier: 'eu-user@example.com',
        credentials: {
          username: 'your-eu-amplitude-api-key',
          password: 'your-eu-amplitude-secret-key',
          domain: 'analytics.eu.amplitude.com',
        },
      })

      Python

      # US region (default) — omit domain or set it to "amplitude.com"
      scalekit_client.connect.upsert_connected_account(
          connection_name="amplitudeanalytics",
          identifier="user@example.com",
          credentials={
              "username": "your-amplitude-api-key",
              "password": "your-amplitude-secret-key",
              "domain": "amplitude.com",
          },
      )
      
      # EU region
      scalekit_client.connect.upsert_connected_account(
          connection_name="amplitudeanalytics",
          identifier="eu-user@example.com",
          credentials={
              "username": "your-eu-amplitude-api-key",
              "password": "your-eu-amplitude-secret-key",
              "domain": "analytics.eu.amplitude.com",
          },
      )

      Running both regions side by side

      If your organization has projects in both the US and EU, create a separate connected account per user (or per project) with the matching domain value. Scalekit routes each account’s requests to the correct regional host automatically — you don’t need separate connections.

What you can do

Connect this agent connector to let your agent:

• Category bulk assign annotation — Assign an existing annotation category to multiple annotations at once
• Create annotation, annotation category, dsar request — Create a chart annotation marking a single date or a date range, either globally visible on all charts or scoped to one chart
• Delete annotation, annotation category, event category — Permanently delete a chart annotation from Amplitude
• Events export — Export raw event data uploaded to Amplitude within a date range as a zip archive of NDJSON files
• Get annotation, annotation category, cohort membership file — Retrieve a single chart annotation by its ID
• List annotation categories, annotations, cohorts — List all chart annotation categories in the Amplitude project, or filter to a single category by name

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

amplitudeanalytics_bulk_assign_annotation_category#Assign an existing annotation category to multiple annotations at once.2 params▾

Assign an existing annotation category to multiple annotations at once.

NameTypeRequiredDescription

annotation_idsarrayrequiredArray of annotation IDs to assign to this category.

category_idintegerrequiredThe ID of the category to assign to the given annotations.

amplitudeanalytics_create_annotation#Create a chart annotation marking a single date or a date range, either globally visible on all charts or scoped to one chart. CONFIRMED (live-tested): category and chart_id are both validated against real resources already known to Amplitude — an unrecognized category name or chart_id 404s rather than being auto-created or accepted as free text; use amplitudeanalytics_create_annotation_category first if the category doesn't exist yet. If category is omitted, Amplitude defaults it to the built-in 'Uncategorized' category rather than leaving it unset (asymmetric with chart_id, which stays genuinely null when omitted). This connector has no chart-listing tool, so chart_id is only usable if you already have a real chart ID from Amplitude's own UI.6 params▾

Create a chart annotation marking a single date or a date range, either globally visible on all charts or scoped to one chart. CONFIRMED (live-tested): category and chart_id are both validated against real resources already known to Amplitude — an unrecognized category name or chart_id 404s rather than being auto-created or accepted as free text; use amplitudeanalytics_create_annotation_category first if the category doesn't exist yet. If category is omitted, Amplitude defaults it to the built-in 'Uncategorized' category rather than leaving it unset (asymmetric with chart_id, which stays genuinely null when omitted). This connector has no chart-listing tool, so chart_id is only usable if you already have a real chart ID from Amplitude's own UI.

NameTypeRequiredDescription

labelstringrequiredThe annotation's display label.

startstringrequiredStart of the annotation's date (or date range), ISO 8601 format (YYYY-MM-DDThh:mmTZD).

categorystringoptionalName of the annotation category to file this under.

chart_idstringoptionalThe chart to scope this annotation to. Omit to create a global annotation visible on all charts.

detailsstringoptionalExtra free-text details about the annotation.

endstringoptionalEnd of the annotation's date range, ISO 8601 format (YYYY-MM-DDThh:mmTZD). Omit for a single-date annotation.

amplitudeanalytics_create_annotation_category#Create a new category for organizing chart annotations in Amplitude.1 param▾

Create a new category for organizing chart annotations in Amplitude.

NameTypeRequiredDescription

categorystringrequiredThe name of the category to create.

amplitudeanalytics_create_dsar_request#Create a Data Subject Access Request (DSAR) job that collects all of a specific user's data from Amplitude for a given date range. Requires a connected account whose API Key/Secret Key fields hold Amplitude's ORGANIZATION-level credentials, not the project-level credentials most other tools in this connector use — create a separate connected account with this connector and enter your organization's API Key and Secret Key in the same username/password fields. Amplitude's org-level keys are not self-service — request them from Amplitude Support (per Amplitude's own docs), they are not generated via the dashboard like project-level keys. CONFIRMED (live-tested): calling this with project-level credentials instead correctly returns a clean 403 'Invalid API Key' — routing, auth header construction, and body mapping all reach Amplitude correctly; the only blocker is the credential tier. Identify the data subject with user_id, amplitude_id, or both — user_id is required if amplitude_id is not set, and amplitude_id is required if user_id is not set; this cross-field requirement cannot be enforced by the input schema alone. Returns 202 Accepted with a numeric requestId — poll amplitudeanalytics_get_dsar_request_status with that ID until the job completes, then download the results with amplitudeanalytics_get_dsar_output_file.4 params▾

Create a Data Subject Access Request (DSAR) job that collects all of a specific user's data from Amplitude for a given date range. Requires a connected account whose API Key/Secret Key fields hold Amplitude's ORGANIZATION-level credentials, not the project-level credentials most other tools in this connector use — create a separate connected account with this connector and enter your organization's API Key and Secret Key in the same username/password fields. Amplitude's org-level keys are not self-service — request them from Amplitude Support (per Amplitude's own docs), they are not generated via the dashboard like project-level keys. CONFIRMED (live-tested): calling this with project-level credentials instead correctly returns a clean 403 'Invalid API Key' — routing, auth header construction, and body mapping all reach Amplitude correctly; the only blocker is the credential tier. Identify the data subject with user_id, amplitude_id, or both — user_id is required if amplitude_id is not set, and amplitude_id is required if user_id is not set; this cross-field requirement cannot be enforced by the input schema alone. Returns 202 Accepted with a numeric requestId — poll amplitudeanalytics_get_dsar_request_status with that ID until the job completes, then download the results with amplitudeanalytics_get_dsar_output_file.

NameTypeRequiredDescription

end_datestringrequiredEnd of the date range to collect the user's data for, in YYYY-MM-DD format.

start_datestringrequiredStart of the date range to collect the user's data for, in YYYY-MM-DD format.

amplitude_idintegeroptionalAmplitude's numeric user ID for the data subject. Required if user_id is not set.

user_idstringoptionalYour application's user ID for the data subject. Required if amplitude_id is not set.

amplitudeanalytics_create_event_category#Create a new event category in Amplitude's taxonomy, used to group related event types.1 param▾

Create a new event category in Amplitude's taxonomy, used to group related event types.

NameTypeRequiredDescription

category_namestringrequiredThe name of the event category to create.

amplitudeanalytics_create_event_property#Create a new event property in Amplitude's taxonomy. If event_type is set, this creates an event-specific property override for that event type; if omitted, this creates a shared property used across all events.10 params▾

Create a new event property in Amplitude's taxonomy. If event_type is set, this creates an event-specific property override for that event type; if omitted, this creates a shared property used across all events.

NameTypeRequiredDescription

event_propertystringrequiredThe name of the event property to create.

classificationsstringoptionalComma-separated classification tags to apply to this property, from: PII, SENSITIVE, REVENUE. Only valid on shared properties — setting this on an event-specific override returns an error.

descriptionstringoptionalA human-readable description of what this event property represents.

enum_valuesstringoptionalComma-separated list of allowed values for this property. Only valid when type is 'enum'.

event_typestringoptionalIf set, scopes this as an event-specific property override for this event type. If omitted, creates a shared property used across all events.

is_array_typebooleanoptionalWhether this property's values are an array of the given type rather than a single value.

is_hiddenbooleanoptionalWhether this property is hidden from the Amplitude UI. Only settable on already-ingested properties.

is_requiredbooleanoptionalWhether this property is required to be present on every occurrence of the event.

regexstringoptionalA regular expression the property's values must match. Only valid when type is 'string'.

typestringoptionalThe property's data type.

amplitudeanalytics_create_event_type#Create a new event type in Amplitude's taxonomy, optionally assigning it a category, description, tags, owner, and visibility flags.10 params▾

Create a new event type in Amplitude's taxonomy, optionally assigning it a category, description, tags, owner, and visibility flags.

NameTypeRequiredDescription

event_typestringrequiredThe name of the event type to create.

categorystringoptionalName of an existing event category to assign this event type to.

descriptionstringoptionalFree-text description of what this event type represents.

is_activebooleanoptionalWhether the event type is active. If omitted, Amplitude applies its own default.

is_hidden_from_dropdownsbooleanoptionalWhether to hide this event type from dropdown selectors. CONFIRMED (live-tested): this took effect immediately on a purely taxonomy-declared event type that was never actually ingested — contrary to Amplitude's documented 'only settable on already-ingested event types' — and setting it true made amplitudeanalytics_get_event_type return 'Not found' for that event even though it remained fully visible in amplitudeanalytics_list_event_types.

is_hidden_from_pathfinderbooleanoptionalWhether to hide this event type from Pathfinder. Amplitude documents this as only settable on already-ingested event types; not independently verified (the sibling is_hidden_from_dropdowns field was confirmed to take effect immediately on a never-ingested event, contrary to its own equivalent documentation, so this one may behave the same way — unconfirmed).

is_hidden_from_persona_resultsbooleanoptionalWhether to hide this event type from Persona results. Amplitude documents this as only settable on already-ingested event types; not independently verified (the sibling is_hidden_from_dropdowns field was confirmed to take effect immediately on a never-ingested event, contrary to its own equivalent documentation, so this one may behave the same way — unconfirmed).

is_hidden_from_timelinebooleanoptionalWhether to hide this event type from Timeline. Amplitude documents this as only settable on already-ingested event types; not independently verified (the sibling is_hidden_from_dropdowns field was confirmed to take effect immediately on a never-ingested event, contrary to its own equivalent documentation, so this one may behave the same way — unconfirmed).

ownerstringoptionalIdentifier or email of the event type's owner.

tagsstringoptionalComma-separated list of tags to apply to this event type.

amplitudeanalytics_create_group_property#Create a new group property in Amplitude's Taxonomy — a custom property scoped to a specific group type (e.g. 'org', 'company') rather than to users or events. Only group_property and group_type are explicitly confirmed by Amplitude's group-property docs; the remaining descriptive fields (description, type, regex, enum_values, is_array_type, is_hidden, classifications) are inferred by analogy with the sibling event/user property taxonomy endpoints and are not explicitly documented for group properties — an incorrect one is simply rejected with a 400, not destructive. No delete or restore endpoint exists for group properties.9 params▾

Create a new group property in Amplitude's Taxonomy — a custom property scoped to a specific group type (e.g. 'org', 'company') rather than to users or events. Only group_property and group_type are explicitly confirmed by Amplitude's group-property docs; the remaining descriptive fields (description, type, regex, enum_values, is_array_type, is_hidden, classifications) are inferred by analogy with the sibling event/user property taxonomy endpoints and are not explicitly documented for group properties — an incorrect one is simply rejected with a 400, not destructive. No delete or restore endpoint exists for group properties.

NameTypeRequiredDescription

group_propertystringrequiredThe name of the group property to create. Per Amplitude's Taxonomy docs, custom group properties may need a 'grp:' prefix (platform-defined properties do not) — this field is confirmed by Amplitude's docs, but verify the exact prefix convention against your account.

classificationsstringoptionalData classification tags to apply to this property (e.g. PII markers), matching whatever classifications are configured in the Amplitude project's data governance settings. INFERRED from the sibling event/user property taxonomy endpoints — Amplitude's group-property docs do not confirm this field exists for group properties; verify empirically before relying on it.

descriptionstringoptionalHuman-readable description of what this property represents. INFERRED from the sibling event/user property taxonomy endpoints — not explicitly confirmed for group properties by Amplitude's docs; verify empirically before relying on it.

enum_valuesstringoptionalAllowed values for this property when type is 'enum'. INFERRED from the sibling event/user property taxonomy endpoints, including the assumption that it's a plain string here rather than an array — not explicitly confirmed for group properties by Amplitude's docs; verify the exact expected format empirically.

group_typestringoptionalThe group type this property belongs to (e.g. 'org', 'company'). Confirmed by Amplitude's Taxonomy docs as a valid create field. Returns 404 if the group type doesn't exist, 409 if the property already exists on that type.

is_array_typebooleanoptionalWhether this property holds an array of values rather than a single value. INFERRED from the sibling event/user property taxonomy endpoints — not explicitly confirmed for group properties by Amplitude's docs; verify empirically before relying on it.

is_hiddenbooleanoptionalWhether this property is hidden from Amplitude's UI pickers (e.g. the chart builder's property list). INFERRED from the sibling event/user property taxonomy endpoints — not explicitly confirmed for group properties by Amplitude's docs; verify empirically before relying on it.

regexstringoptionalA regular expression that values of this property must match. INFERRED from the sibling event/user property taxonomy endpoints — not explicitly confirmed for group properties by Amplitude's docs; verify empirically before relying on it.

typestringoptionalThe data type of this property. INFERRED from the sibling event/user property taxonomy endpoints — not explicitly confirmed for group properties by Amplitude's docs; verify empirically before relying on it.

amplitudeanalytics_create_release#Create a release annotation in Amplitude, marking a version rollout with a start (and optionally end) time. When chart_visibility is true (the default), the release appears as an annotation on charts. Amplitude's docs only document a 200 success response and a 400 bad-request response for this endpoint — there is no documented 201.8 params▾

Create a release annotation in Amplitude, marking a version rollout with a start (and optionally end) time. When chart_visibility is true (the default), the release appears as an annotation on charts. Amplitude's docs only document a 200 success response and a 400 bad-request response for this endpoint — there is no documented 201.

NameTypeRequiredDescription

release_startstringrequiredStart date/time of the release window, format 'yyyy-MM-dd HH:mm:ss' in UTC.

titlestringrequiredName of this release, shown wherever the release annotation is displayed.

versionstringrequiredVersion identifier for this release.

chart_visibilitybooleanoptionalWhen true, this release appears as an annotation on charts. Defaults to true.

created_bystringoptionalName or identifier of who created this release, for display purposes.

descriptionstringoptionalFree-text description of what this release contains.

platformsarrayoptionalPlatforms this release applies to.

release_endstringoptionalEnd date/time of the release window, format 'yyyy-MM-dd HH:mm:ss' in UTC. Omit for an open-ended release.

amplitudeanalytics_create_user_property#Create a new user property in Amplitude's taxonomy. Unlike event properties, user properties have no event_type or is_required field — they always apply globally to the user profile, not to a specific event.8 params▾

Create a new user property in Amplitude's taxonomy. Unlike event properties, user properties have no event_type or is_required field — they always apply globally to the user profile, not to a specific event.

NameTypeRequiredDescription

user_propertystringrequiredThe name of the user property to create. CONFIRMED (live-tested): Amplitude auto-prepends 'gp:' to custom user property names regardless of whether you include it here — the property is always stored with the prefix. Use amplitudeanalytics_list_user_properties afterward to see the actual stored name, and use that exact name (with 'gp:') for amplitudeanalytics_get_user_property.

classificationsstringoptionalComma-separated classification tags to apply to this property, from: PII, SENSITIVE, REVENUE.

descriptionstringoptionalA human-readable description of what this user property represents.

enum_valuesstringoptionalComma-separated list of allowed values for this property. Only valid when type is 'enum'.

is_array_typebooleanoptionalWhether this property's values are an array of the given type rather than a single value.

is_hiddenbooleanoptionalWhether this property is hidden from the Amplitude UI.

regexstringoptionalA regular expression the property's values must match. Only valid when type is 'string'.

typestringoptionalThe property's data type.

amplitudeanalytics_delete_annotation#Permanently delete a chart annotation from Amplitude.1 param▾

Permanently delete a chart annotation from Amplitude.

NameTypeRequiredDescription

annotation_idintegerrequiredThe ID of the annotation to delete.

amplitudeanalytics_delete_annotation_category#Permanently delete a chart annotation category from Amplitude. This does not delete the annotations that used this category, only the category grouping itself.1 param▾

Permanently delete a chart annotation category from Amplitude. This does not delete the annotations that used this category, only the category grouping itself.

NameTypeRequiredDescription

category_idintegerrequiredThe ID of the annotation category to delete.

amplitudeanalytics_delete_event_category#Permanently delete an event category from Amplitude's taxonomy.1 param▾

Permanently delete an event category from Amplitude's taxonomy.

NameTypeRequiredDescription

category_idstringrequiredThe id of the event category to delete, as used in the Amplitude Taxonomy API path. Treated as an opaque string identifier (not necessarily numeric).

amplitudeanalytics_delete_event_property#Delete an event property from Amplitude's taxonomy. amplitudeanalytics_restore_event_property can undo this, but CONFIRMED (live-tested) only for properties that were previously 'live' (actually seen on ingested events) — deleting a purely taxonomy-declared property that was never ingested removes it entirely, and restore will then fail with 'Not found'.1 param▾

Delete an event property from Amplitude's taxonomy. amplitudeanalytics_restore_event_property can undo this, but CONFIRMED (live-tested) only for properties that were previously 'live' (actually seen on ingested events) — deleting a purely taxonomy-declared property that was never ingested removes it entirely, and restore will then fail with 'Not found'.

NameTypeRequiredDescription

event_propertystringrequiredThe name of the event property to delete.

amplitudeanalytics_delete_event_type#Delete an event type from Amplitude's taxonomy. Deletion is state-machine driven: a 'live' event type is marked deleted; an 'unexpected' event type is first added to the tracking plan then deleted; a 'planned' event type is simply removed from the plan; a 'transformed' event type CANNOT be deleted (the API returns an error); an already-deleted or not-found event type also errors. CONFIRMED (live-tested): for a 'planned' event type — i.e. one created directly through amplitudeanalytics_create_event_type and never actually ingested — deletion fully removes it from the plan rather than soft-deleting it. amplitudeanalytics_restore_event_type will fail with 'Not found' afterward; restore only works for event types that were previously 'live' (actually ingested) before being soft-deleted.1 param▾

Delete an event type from Amplitude's taxonomy. Deletion is state-machine driven: a 'live' event type is marked deleted; an 'unexpected' event type is first added to the tracking plan then deleted; a 'planned' event type is simply removed from the plan; a 'transformed' event type CANNOT be deleted (the API returns an error); an already-deleted or not-found event type also errors. CONFIRMED (live-tested): for a 'planned' event type — i.e. one created directly through amplitudeanalytics_create_event_type and never actually ingested — deletion fully removes it from the plan rather than soft-deleting it. amplitudeanalytics_restore_event_type will fail with 'Not found' afterward; restore only works for event types that were previously 'live' (actually ingested) before being soft-deleted.

NameTypeRequiredDescription

event_typestringrequiredThe name of the event type to delete.

amplitudeanalytics_delete_user_property#Delete a custom user property from Amplitude's taxonomy. Amplitude-owned (built-in) user properties cannot be deleted through this API and will return an error. amplitudeanalytics_restore_user_property can undo this, but CONFIRMED (live-tested) only for properties that were previously 'live' (actually seen on ingested events) — deleting a purely taxonomy-declared property that was never ingested removes it entirely, and restore will then fail with 'Not found'.1 param▾

Delete a custom user property from Amplitude's taxonomy. Amplitude-owned (built-in) user properties cannot be deleted through this API and will return an error. amplitudeanalytics_restore_user_property can undo this, but CONFIRMED (live-tested) only for properties that were previously 'live' (actually seen on ingested events) — deleting a purely taxonomy-declared property that was never ingested removes it entirely, and restore will then fail with 'Not found'.

NameTypeRequiredDescription

user_propertystringrequiredThe name of the user property to delete. Amplitude-owned (built-in) user properties cannot be deleted through this API and will return an error.

amplitudeanalytics_export_events#Export raw event data uploaded to Amplitude within a date range as a zip archive of NDJSON files. The response is a binary zip file, not JSON — save it to disk rather than parsing it as JSON. start and end use the YYYYMMDDTHH format (e.g. 20220201T05), and the start-end range cannot exceed 365 days. Exported events reflect each event's upload time to Amplitude, not its original client-side event time, and typically become available roughly 2 hours after upload. The response is capped at 4GB; a range that would exceed that returns a 400 error — use Amplitude's Amazon S3 export instead for larger data. Returns 404 if there is no data in the requested range, and 504 if the export is too large and times out while being generated.2 params▾

Export raw event data uploaded to Amplitude within a date range as a zip archive of NDJSON files. The response is a binary zip file, not JSON — save it to disk rather than parsing it as JSON. start and end use the YYYYMMDDTHH format (e.g. 20220201T05), and the start-end range cannot exceed 365 days. Exported events reflect each event's upload time to Amplitude, not its original client-side event time, and typically become available roughly 2 hours after upload. The response is capped at 4GB; a range that would exceed that returns a 400 error — use Amplitude's Amazon S3 export instead for larger data. Returns 404 if there is no data in the requested range, and 504 if the export is too large and times out while being generated.

NameTypeRequiredDescription

endstringrequiredEnd of the export range, in YYYYMMDDTHH format (year, month, day, hour). The start-end range cannot exceed 365 days.

startstringrequiredStart of the export range, in YYYYMMDDTHH format (year, month, day, hour).

amplitudeanalytics_get_annotation#Retrieve a single chart annotation by its ID.1 param▾

Retrieve a single chart annotation by its ID.

NameTypeRequiredDescription

annotation_idintegerrequiredThe ID of the annotation to retrieve.

amplitudeanalytics_get_annotation_category#Retrieve a single chart annotation category by its ID.1 param▾

Retrieve a single chart annotation category by its ID.

NameTypeRequiredDescription

category_idintegerrequiredThe ID of the annotation category to retrieve.

amplitudeanalytics_get_cohort_membership_file#Download the completed cohort membership export started with amplitudeanalytics_request_cohort_membership, once amplitudeanalytics_get_cohort_membership_status reports it complete. Small cohorts return the gzip-compressed member data directly; large cohorts return an HTTP 302 redirect to a pre-signed download URL valid for 1 minute (the request_id-based link itself stays valid for 7 days). CONFIRMED (live-tested): routing, auth, and path-templating all work correctly — a numeric request_id gets a clean, well-formed error: {"details":"Cohort download not found"}. IMPORTANT CONFIRMED QUIRK (same pattern as get_cohort_membership_status and the DSAR API's get_dsar_request_status): a non-numeric request_id instead returns a generic, unhelpful raw HTML '404: Not Found' from an edge/routing layer in front of Amplitude, before its own logic runs. Always pass the exact request_id returned by amplitudeanalytics_request_cohort_membership.1 param▾

Download the completed cohort membership export started with amplitudeanalytics_request_cohort_membership, once amplitudeanalytics_get_cohort_membership_status reports it complete. Small cohorts return the gzip-compressed member data directly; large cohorts return an HTTP 302 redirect to a pre-signed download URL valid for 1 minute (the request_id-based link itself stays valid for 7 days). CONFIRMED (live-tested): routing, auth, and path-templating all work correctly — a numeric request_id gets a clean, well-formed error: {"details":"Cohort download not found"}. IMPORTANT CONFIRMED QUIRK (same pattern as get_cohort_membership_status and the DSAR API's get_dsar_request_status): a non-numeric request_id instead returns a generic, unhelpful raw HTML '404: Not Found' from an edge/routing layer in front of Amplitude, before its own logic runs. Always pass the exact request_id returned by amplitudeanalytics_request_cohort_membership.

NameTypeRequiredDescription

request_idstringrequiredThe request_id returned by amplitudeanalytics_request_cohort_membership, must be in a completed state per amplitudeanalytics_get_cohort_membership_status. CONFIRMED: a non-numeric value returns a generic, unhelpful raw HTML 404 rather than a clear error (same pattern as the DSAR API's request_id) — always use the exact value returned.

amplitudeanalytics_get_cohort_membership_status#Check the status of an asynchronous cohort membership export previously started with amplitudeanalytics_request_cohort_membership. Once the status reports completion, call amplitudeanalytics_get_cohort_membership_file to download the data. Note: Amplitude's documented async_status values are inconsistently formatted across their own sources (space-separated like "JOB COMPLETED" on the current docs page, vs underscore-separated "JOB_COMPLETED" seen elsewhere) — treat the exact string loosely (e.g. case/format-insensitive contains-"COMPLETE" check) rather than a strict equality match. CONFIRMED (live-tested): routing, auth, and path-templating all work correctly — a numeric request_id (matching the numeric-looking IDs Amplitude actually issues) gets a clean, well-formed error: {"details":"No job exists with request_id: <id>"}. IMPORTANT CONFIRMED QUIRK (same pattern found on the DSAR API's get_dsar_request_status): a non-numeric request_id instead returns a generic, unhelpful raw HTML '404: Not Found' from what appears to be an edge/routing layer in front of Amplitude, before its own logic runs. Always pass the exact request_id string returned by amplitudeanalytics_request_cohort_membership, not an arbitrary placeholder.1 param▾

Check the status of an asynchronous cohort membership export previously started with amplitudeanalytics_request_cohort_membership. Once the status reports completion, call amplitudeanalytics_get_cohort_membership_file to download the data. Note: Amplitude's documented async_status values are inconsistently formatted across their own sources (space-separated like "JOB COMPLETED" on the current docs page, vs underscore-separated "JOB_COMPLETED" seen elsewhere) — treat the exact string loosely (e.g. case/format-insensitive contains-"COMPLETE" check) rather than a strict equality match. CONFIRMED (live-tested): routing, auth, and path-templating all work correctly — a numeric request_id (matching the numeric-looking IDs Amplitude actually issues) gets a clean, well-formed error: {"details":"No job exists with request_id: <id>"}. IMPORTANT CONFIRMED QUIRK (same pattern found on the DSAR API's get_dsar_request_status): a non-numeric request_id instead returns a generic, unhelpful raw HTML '404: Not Found' from what appears to be an edge/routing layer in front of Amplitude, before its own logic runs. Always pass the exact request_id string returned by amplitudeanalytics_request_cohort_membership, not an arbitrary placeholder.

NameTypeRequiredDescription

request_idstringrequiredThe request_id returned by amplitudeanalytics_request_cohort_membership. CONFIRMED: a non-numeric value returns a generic, unhelpful raw HTML 404 rather than a clear error (same pattern as the DSAR API's request_id) — always use the exact value amplitudeanalytics_request_cohort_membership returned.

amplitudeanalytics_get_cohort_usage#Check how much of the Behavioral Cohorts Download API's monthly quota has been used. Growth and Enterprise plans are limited to 500 download requests per month; this shows the current usage count and when it resets.0 params▾

Check how much of the Behavioral Cohorts Download API's monthly quota has been used. Growth and Enterprise plans are limited to 500 download requests per month; this shows the current usage count and when it resets.

amplitudeanalytics_get_dsar_output_file#Download a single completed output file from a Data Subject Access Request (DSAR) job. Requires a connected account whose API Key/Secret Key fields hold Amplitude's ORGANIZATION-level credentials, not the project-level credentials most other tools in this connector use — use the same separate, organization-credentialed connected account you used to create the request. Amplitude's org-level keys are not self-service — request them from Amplitude Support. CONFIRMED (live-tested): calling this with project-level credentials instead correctly returns a clean 403 'Invalid API Key' — routing and path-templating reach Amplitude correctly; the only blocker is the credential tier. Call this only after amplitudeanalytics_get_dsar_request_status reports the job's status as done, using the request_id of that job and an output_id taken from one of the URLs in its urls list. The response is the raw output file itself, not JSON.2 params▾

Download a single completed output file from a Data Subject Access Request (DSAR) job. Requires a connected account whose API Key/Secret Key fields hold Amplitude's ORGANIZATION-level credentials, not the project-level credentials most other tools in this connector use — use the same separate, organization-credentialed connected account you used to create the request. Amplitude's org-level keys are not self-service — request them from Amplitude Support. CONFIRMED (live-tested): calling this with project-level credentials instead correctly returns a clean 403 'Invalid API Key' — routing and path-templating reach Amplitude correctly; the only blocker is the credential tier. Call this only after amplitudeanalytics_get_dsar_request_status reports the job's status as done, using the request_id of that job and an output_id taken from one of the URLs in its urls list. The response is the raw output file itself, not JSON.

NameTypeRequiredDescription

output_idintegerrequiredAn integer identifying which output file to download, taken from one of the download URLs in amplitudeanalytics_get_dsar_request_status's urls list.

request_idintegerrequiredThe requestId of the DSAR job, from amplitudeanalytics_create_dsar_request or amplitudeanalytics_get_dsar_request_status.

amplitudeanalytics_get_dsar_request_status#Check the status of a Data Subject Access Request (DSAR) job previously created with amplitudeanalytics_create_dsar_request. Requires a connected account whose API Key/Secret Key fields hold Amplitude's ORGANIZATION-level credentials, not the project-level credentials most other tools in this connector use — use the same separate, organization-credentialed connected account you used to create the request. Amplitude's org-level keys are not self-service — request them from Amplitude Support. CONFIRMED (live-tested): calling this with project-level credentials and a purely numeric request_id (matching the integer requestId Amplitude actually returns from create_dsar_request) correctly returns a clean 403 'Invalid API Key' — routing and path-templating reach Amplitude correctly; the only blocker is the credential tier. FIXED: request_id is typed as an integer (matching the requestId Amplitude actually returns and amplitudeanalytics_get_dsar_output_file's own request_id type) specifically because a non-numeric value was confirmed to produce a generic, unhelpful raw HTML '404: Not Found' from a routing layer in front of Amplitude, instead of a clear error — the integer type now rejects a malformed value immediately with a clear schema-validation error rather than letting it round-trip to that confusing response. The response includes status (one of staging, submitted, done, or failed), failReason if the job failed, urls with download links once the job is done, and expires indicating when those download links expire. Once status is done, download the output files with amplitudeanalytics_get_dsar_output_file.1 param▾

Check the status of a Data Subject Access Request (DSAR) job previously created with amplitudeanalytics_create_dsar_request. Requires a connected account whose API Key/Secret Key fields hold Amplitude's ORGANIZATION-level credentials, not the project-level credentials most other tools in this connector use — use the same separate, organization-credentialed connected account you used to create the request. Amplitude's org-level keys are not self-service — request them from Amplitude Support. CONFIRMED (live-tested): calling this with project-level credentials and a purely numeric request_id (matching the integer requestId Amplitude actually returns from create_dsar_request) correctly returns a clean 403 'Invalid API Key' — routing and path-templating reach Amplitude correctly; the only blocker is the credential tier. FIXED: request_id is typed as an integer (matching the requestId Amplitude actually returns and amplitudeanalytics_get_dsar_output_file's own request_id type) specifically because a non-numeric value was confirmed to produce a generic, unhelpful raw HTML '404: Not Found' from a routing layer in front of Amplitude, instead of a clear error — the integer type now rejects a malformed value immediately with a clear schema-validation error rather than letting it round-trip to that confusing response. The response includes status (one of staging, submitted, done, or failed), failReason if the job failed, urls with download links once the job is done, and expires indicating when those download links expire. Once status is done, download the output files with amplitudeanalytics_get_dsar_output_file.

NameTypeRequiredDescription

request_idintegerrequiredThe requestId returned when the DSAR job was created with amplitudeanalytics_create_dsar_request, used to check this specific job's status. Typed as an integer (not a string) because a non-numeric value was confirmed to produce a confusing raw HTML 404 from a routing layer in front of Amplitude, rather than a clear error — this type constraint rejects bad input immediately instead.

amplitudeanalytics_get_event_category#Retrieve a single event category from Amplitude's taxonomy, looked up by its category_name. Unlike amplitudeanalytics_update_event_category and amplitudeanalytics_delete_event_category (which are keyed by category_id), this endpoint is keyed by category_name — this matches Amplitude's documented Taxonomy API and is not an inconsistency to fix.1 param▾

Retrieve a single event category from Amplitude's taxonomy, looked up by its category_name. Unlike amplitudeanalytics_update_event_category and amplitudeanalytics_delete_event_category (which are keyed by category_id), this endpoint is keyed by category_name — this matches Amplitude's documented Taxonomy API and is not an inconsistency to fix.

NameTypeRequiredDescription

category_namestringrequiredThe name of the event category to retrieve.

amplitudeanalytics_get_event_segmentation#Pull Event Segmentation chart data from the Amplitude Dashboard REST API: measure an event (uniques, totals, or another metric) over a date range, with optional segment filters and up to two group-by properties. Rate limits: 5 concurrent requests shared with other Amplitude Dashboard/Cohort API calls. CONFIRMED (live-tested): the measurement values histogram, sums, and value_avg require a group-by, but NOT via the separate group_by field on this tool — that field maps to the chart-level g parameter, which these three measurement types ignore for their own validation. Instead, embed group_by directly inside the event field's own JSON string, e.g. event: '{"event_type":"session_start","group_by":[{"type":"event","value":"gp:country"}]}'. Without this, Amplitude rejects the request with 'Missing required group bys' regardless of what the group_by field is set to. uniques, totals, average, pct_dau, and formula do not have this requirement and work correctly with the separate group_by/second_group_by fields.14 params▾

Pull Event Segmentation chart data from the Amplitude Dashboard REST API: measure an event (uniques, totals, or another metric) over a date range, with optional segment filters and up to two group-by properties. Rate limits: 5 concurrent requests shared with other Amplitude Dashboard/Cohort API calls. CONFIRMED (live-tested): the measurement values histogram, sums, and value_avg require a group-by, but NOT via the separate group_by field on this tool — that field maps to the chart-level g parameter, which these three measurement types ignore for their own validation. Instead, embed group_by directly inside the event field's own JSON string, e.g. event: '{"event_type":"session_start","group_by":[{"type":"event","value":"gp:country"}]}'. Without this, Amplitude rejects the request with 'Missing required group bys' regardless of what the group_by field is set to. uniques, totals, average, pct_dau, and formula do not have this requirement and work correctly with the separate group_by/second_group_by fields.

NameTypeRequiredDescription

endstringrequiredEnd date of the query range, format YYYYMMDD (e.g. 20260131).

eventstringrequiredJSON-encoded primary event definition: {"event_type": "...", "filters"?: [{"subprop_type", "subprop_key", "subprop_op", "subprop_value"}], "group_by"?: [{"type", "value"}]}. Example: {"event_type":"sign_up"}.

startstringrequiredStart date of the query range, format YYYYMMDD (e.g. 20260101).

formulastringoptionalFormula expression combining event A and (optionally) event B, e.g. "UNIQUES(A)/UNIQUES(B)". Required only when measurement is set to "formula"; ignored otherwise.

group_bystringoptionalProperty to group results by, e.g. gp:country or a user/event property name.

intervalintegeroptionalTime bucket size for the returned series: -300000 (real-time), -3600000 (hourly), 1 (daily), 7 (weekly), or 30 (monthly). Defaults to 1.

limitintegeroptionalMaximum number of group-by values to return (max 1000). Defaults to 100.

measurementstringoptionalAggregation to compute: uniques, totals, pct_dau, average, histogram, sums, value_avg, or formula. Defaults to uniques. CONFIRMED: histogram, sums, and value_avg require a group-by embedded inside the event field's own JSON (e.g. {"event_type":"...","group_by":[{"type":"event","value":"gp:country"}]}) — the separate group_by field on this tool does not satisfy this requirement for these three measurements specifically.

rolling_averageintegeroptionalRolling average window size, in units of the chosen interval (days/weeks/months). Smooths the returned series.

rolling_windowintegeroptionalRolling window size, in units of the chosen interval (days/weeks/months). Aggregates each point over a trailing window.

second_eventstringoptionalJSON-encoded second event definition, same shape as event. Used together with formula to compare two events.

second_group_bystringoptionalSecond property to group results by, applied after group_by.

segment_definitionsstringoptionalJSON-encoded array of segment definitions to split the event by cohort/property segments, e.g. [{"prop":"gp:country","op":"is","values":["US"]}].

user_typestringoptionalRestrict the measurement to a user type: any (all users) or active (only currently active users). Defaults to any.

amplitudeanalytics_get_event_streaming_metrics#Get the delivery-metrics summary for an Amplitude Event Streaming sync over a time window. The response includes timePeriod, eventsDelivered, eventsNotDelivered, deliveryRate, latencyInSeconds (p95), successOnFirstAttempt, successAfterRetry, eventsExpired, and eventsDiscarded. Amplitude retains at most 90 days of data for this endpoint — requesting an older range returns a 500 error.4 params▾

Get the delivery-metrics summary for an Amplitude Event Streaming sync over a time window. The response includes timePeriod, eventsDelivered, eventsNotDelivered, deliveryRate, latencyInSeconds (p95), successOnFirstAttempt, successAfterRetry, eventsExpired, and eventsDiscarded. Amplitude retains at most 90 days of data for this endpoint — requesting an older range returns a 500 error.

NameTypeRequiredDescription

sync_idstringrequiredThe Event Streaming sync to get delivery metrics for.

time_periodstringrequiredPreset time window to summarize metrics over. Use CUSTOM together with start and end for an explicit window.

endstringoptionalExclusive end of the custom time window, ISO 8601. Required only when time_period is CUSTOM.

startstringoptionalInclusive start of the custom time window, ISO 8601. Required only when time_period is CUSTOM.

amplitudeanalytics_get_event_type#Retrieve a single event type from Amplitude's taxonomy by its event_type name. CONFIRMED (live-tested): if the event type has is_hidden_from_dropdowns set to true, this single-item lookup returns 'Not found' even though the event type still fully exists and appears in amplitudeanalytics_list_event_types — this is a real, reproducible quirk of this specific endpoint, not a sign the event is missing. If a lookup unexpectedly 404s, check amplitudeanalytics_list_event_types first before assuming the event doesn't exist.1 param▾

Retrieve a single event type from Amplitude's taxonomy by its event_type name. CONFIRMED (live-tested): if the event type has is_hidden_from_dropdowns set to true, this single-item lookup returns 'Not found' even though the event type still fully exists and appears in amplitudeanalytics_list_event_types — this is a real, reproducible quirk of this specific endpoint, not a sign the event is missing. If a lookup unexpectedly 404s, check amplitudeanalytics_list_event_types first before assuming the event doesn't exist.

NameTypeRequiredDescription

event_typestringrequiredThe name of the event type to retrieve.

amplitudeanalytics_get_funnel_results#Pull Funnel Analysis chart data from the Amplitude Dashboard REST API: step-by-step conversion and drop-off for an ordered (or unordered/sequential) sequence of two or more events over a date range. Rate limits: 5 concurrent requests shared with other Amplitude Dashboard/Cohort API calls.10 params▾

Pull Funnel Analysis chart data from the Amplitude Dashboard REST API: step-by-step conversion and drop-off for an ordered (or unordered/sequential) sequence of two or more events over a date range. Rate limits: 5 concurrent requests shared with other Amplitude Dashboard/Cohort API calls.

NameTypeRequiredDescription

endstringrequiredEnd date of the query range, format YYYYMMDD (e.g. 20260131).

funnel_stepsarrayrequiredOrdered array of JSON-encoded event definitions describing the funnel steps, at least 2 required, e.g. ["{\"event_type\":\"sign_up\"}", "{\"event_type\":\"activated\"}"]. Each array element is sent as a repeated `e` query parameter in step order.

startstringrequiredStart date of the query range, format YYYYMMDD (e.g. 20260101).

conversion_window_secondsintegeroptionalMaximum time, in seconds, a user has to complete the full funnel after the first step. Defaults to 2592000 (30 days).

group_bystringoptionalProperty to group results by, e.g. gp:country. Funnels support only one group-by property (unlike event segmentation, which supports two).

intervalintegeroptionalTime bucket size for the returned series: -300000 (real-time), -3600000 (hourly), 1 (daily), 7 (weekly), or 30 (monthly). Defaults to 1.

limitintegeroptionalMaximum number of group-by values to return (max 1000). Defaults to 100.

modestringoptionalStep-order strictness: ordered (steps must occur in the given order), unordered (any order), or sequential (given order, with no other funnel events occurring in between). Defaults to ordered.

segment_definitionsstringoptionalJSON-encoded array of segment definitions to split the funnel by cohort/property segments, e.g. [{"prop":"gp:country","op":"is","values":["US"]}].

user_filterstringoptionalRestrict the funnel to a user type: new (users new in the date range) or active (currently active users). Defaults to active. Note: this is a DIFFERENT enum than amplitudeanalytics_get_event_segmentation's user_type field (which uses any/active).

amplitudeanalytics_get_group_property#Retrieve a single group property from Amplitude's Taxonomy by name.1 param▾

Retrieve a single group property from Amplitude's Taxonomy by name.

NameTypeRequiredDescription

group_propertystringrequiredThe name of the group property to retrieve.

amplitudeanalytics_get_session_replay_files#Get download links for a single Amplitude session replay's recorded event files. Returns a files array of presigned S3 URLs — these URLs expire after 15 minutes, so download the files promptly after calling this.4 params▾

Get download links for a single Amplitude session replay's recorded event files. Returns a files array of presigned S3 URLs — these URLs expire after 15 minutes, so download the files promptly after calling this.

NameTypeRequiredDescription

replay_idstringrequiredThe replay to fetch files for, formatted as 'device_id/session_id'.

page_sizeintegeroptionalMaximum number of file entries to return per page. Maximum 1000.

page_tokenstringoptionalOpaque pagination cursor from a previous response.

versionintegeroptionalSession replay data format version to request.

amplitudeanalytics_get_user_mapping#Look up user identity mappings (aliases) for one or more Amplitude user IDs. The response is an object keyed by each requested user_id, where each value has mapped_from[] and mapped_to[] arrays of {amplitude_id, user_id} pairs describing merged/aliased identities. This is the only User Mapping (Aliasing) API endpoint included in this connector — it uses project-level HTTP Basic Auth, matching the rest of this connector's tools, while the write/map/unmap endpoints live on a different host entirely and are intentionally excluded. CONFIRMED (live-tested): this parameter is genuinely sent as a JSON request body on a GET request (non-standard, but this codebase's HTTP layer attaches a body regardless of method) — an empty user_ids array produced the specific Amplitude error 'Request must have a list of userIds', which only makes sense if Amplitude actually received and inspected the array, proving the GET-with-body mechanism delivers this field end-to-end.1 param▾

Look up user identity mappings (aliases) for one or more Amplitude user IDs. The response is an object keyed by each requested user_id, where each value has mapped_from[] and mapped_to[] arrays of {amplitude_id, user_id} pairs describing merged/aliased identities. This is the only User Mapping (Aliasing) API endpoint included in this connector — it uses project-level HTTP Basic Auth, matching the rest of this connector's tools, while the write/map/unmap endpoints live on a different host entirely and are intentionally excluded. CONFIRMED (live-tested): this parameter is genuinely sent as a JSON request body on a GET request (non-standard, but this codebase's HTTP layer attaches a body regardless of method) — an empty user_ids array produced the specific Amplitude error 'Request must have a list of userIds', which only makes sense if Amplitude actually received and inspected the array, proving the GET-with-body mechanism delivers this field end-to-end.

NameTypeRequiredDescription

user_idsarrayrequiredAmplitude user IDs to look up mappings for (1 to 100 IDs per request).

amplitudeanalytics_get_user_property#Retrieve a single user property by name from Amplitude's taxonomy. CONFIRMED (live-tested): Amplitude auto-prepends 'gp:' to custom user property names on creation regardless of what name amplitudeanalytics_create_user_property was called with — use amplitudeanalytics_list_user_properties to see each property's actual stored name (e.g. 'gp:plan_type'), and pass that exact name here. Passing the plain, unprefixed name returns 'Not found' even immediately after a successful create.1 param▾

Retrieve a single user property by name from Amplitude's taxonomy. CONFIRMED (live-tested): Amplitude auto-prepends 'gp:' to custom user property names on creation regardless of what name amplitudeanalytics_create_user_property was called with — use amplitudeanalytics_list_user_properties to see each property's actual stored name (e.g. 'gp:plan_type'), and pass that exact name here. Passing the plain, unprefixed name returns 'Not found' even immediately after a successful create.

NameTypeRequiredDescription

user_propertystringrequiredThe name of the user property to retrieve, exactly as stored by Amplitude. CONFIRMED: custom properties are auto-prefixed with 'gp:' on creation — use amplitudeanalytics_list_user_properties to find the exact stored name if a plain lookup returns 'Not found'.

amplitudeanalytics_list_annotation_categories#List all chart annotation categories in the Amplitude project, or filter to a single category by name.1 param▾

List all chart annotation categories in the Amplitude project, or filter to a single category by name.

NameTypeRequiredDescription

categorystringoptionalIf set, only returns the category matching this exact name instead of all categories.

amplitudeanalytics_list_annotations#List chart annotations, optionally filtered by category, by chart, or by a date range. CONFIRMED (live-tested): category and chart_id do NOT combine as a logical AND, and Amplitude does NOT error if both are set — category silently wins and chart_id is dropped entirely, even when the chart_id value is otherwise invalid (an invalid chart_id alone 404s, but the identical value alongside a valid category causes no error at all). Set only one of the two at a time; if both are set, only category takes effect. chart_id also only accepts real chart IDs already known to Amplitude's project (it 404s on an unknown value) — this connector has no chart-listing tool, so chart-scoped filtering/annotations are only usable if you already have a real chart_id from Amplitude's own UI.4 params▾

List chart annotations, optionally filtered by category, by chart, or by a date range. CONFIRMED (live-tested): category and chart_id do NOT combine as a logical AND, and Amplitude does NOT error if both are set — category silently wins and chart_id is dropped entirely, even when the chart_id value is otherwise invalid (an invalid chart_id alone 404s, but the identical value alongside a valid category causes no error at all). Set only one of the two at a time; if both are set, only category takes effect. chart_id also only accepts real chart IDs already known to Amplitude's project (it 404s on an unknown value) — this connector has no chart-listing tool, so chart-scoped filtering/annotations are only usable if you already have a real chart_id from Amplitude's own UI.

NameTypeRequiredDescription

categorystringoptionalFilter to annotations in this category. CONFIRMED: if chart_id is also set, this one silently wins — chart_id is dropped without error.

chart_idstringoptionalFilter to annotations scoped to this chart. CONFIRMED: if category is also set, this field is silently ignored (no error, no effect) — category wins. Must be a real chart ID Amplitude recognizes; an unknown value 404s when used alone.

endstringoptionalOnly return annotations before this ISO 8601 timestamp.

startstringoptionalOnly return annotations after this ISO 8601 timestamp.

amplitudeanalytics_list_cohorts#List all behavioral cohorts defined in the Amplitude project. Returns each cohort's id, name, description, size, published/archived state, owners, viewers, definition, and last-computed time. Use this to find a cohort's id before calling amplitudeanalytics_request_cohort_membership.1 param▾

List all behavioral cohorts defined in the Amplitude project. Returns each cohort's id, name, description, size, published/archived state, owners, viewers, definition, and last-computed time. Use this to find a cohort's id before calling amplitudeanalytics_request_cohort_membership.

NameTypeRequiredDescription

include_sync_infobooleanoptionalIf true, include each cohort's sync destination metadata (syncMetadata) in the response — e.g. which downstream destinations (ad platforms, warehouses) the cohort is synced to. Defaults to false.

amplitudeanalytics_list_event_categories#List all event categories defined in Amplitude's taxonomy.0 params▾

List all event categories defined in Amplitude's taxonomy.

amplitudeanalytics_list_event_properties#Get the event properties defined in Amplitude's taxonomy — either the shared properties used across all events, or (if event_type is set) the properties specific to one event type. Note: per Amplitude's documentation, this parameter is sent as a JSON request body on a GET request (non-standard); this matches the documented behavior but has not been empirically verified against a live account — if it fails, the parameter may need to move to a query string instead.1 param▾

Get the event properties defined in Amplitude's taxonomy — either the shared properties used across all events, or (if event_type is set) the properties specific to one event type. Note: per Amplitude's documentation, this parameter is sent as a JSON request body on a GET request (non-standard); this matches the documented behavior but has not been empirically verified against a live account — if it fails, the parameter may need to move to a query string instead.

NameTypeRequiredDescription

event_typestringoptionalIf set, returns properties specific to this event type. If omitted, returns the shared properties used across all events.

amplitudeanalytics_list_event_types#List event types defined in Amplitude's taxonomy, optionally including deleted ones.1 param▾

List event types defined in Amplitude's taxonomy, optionally including deleted ones.

NameTypeRequiredDescription

show_deletedbooleanoptionalInclude deleted event types in the results. Defaults to excluding them.

amplitudeanalytics_list_group_properties#List group properties defined in Amplitude's Taxonomy. Pass group_type to scope the list to that group type (e.g. 'org'); omit it to list properties shared across group types rather than any single type's properties.1 param▾

List group properties defined in Amplitude's Taxonomy. Pass group_type to scope the list to that group type (e.g. 'org'); omit it to list properties shared across group types rather than any single type's properties.

NameTypeRequiredDescription

group_typestringoptionalGroup type to filter the list to. If omitted, returns properties shared across group types rather than any single type's properties.

amplitudeanalytics_list_session_replays#List Amplitude Session Replay recordings, optionally filtered by time range, Amplitude user ID, or an explicit set of replay IDs, with pagination and sort order control. amplitude_id and replay_id are mutually exclusive filters, and replay_id is also mutually exclusive with page_token; when replay_id is set, page_size is ignored and the response's next_page_token is always null. Each replay in the response includes replay_id, session_id, device_id, amplitude_id, start_time, end_time, and retention_in_days, plus a top-level next_page_token for pagination.7 params▾

List Amplitude Session Replay recordings, optionally filtered by time range, Amplitude user ID, or an explicit set of replay IDs, with pagination and sort order control. amplitude_id and replay_id are mutually exclusive filters, and replay_id is also mutually exclusive with page_token; when replay_id is set, page_size is ignored and the response's next_page_token is always null. Each replay in the response includes replay_id, session_id, device_id, amplitude_id, start_time, end_time, and retention_in_days, plus a top-level next_page_token for pagination.

NameTypeRequiredDescription

amplitude_idintegeroptionalFilter to session replays for this Amplitude user ID. Mutually exclusive with replay_id — set one or the other, not both.

end_timestringoptionalUpper bound (ISO 8601) on replay start time — only return replays that started before this time.

page_sizeintegeroptionalMaximum number of replays to return per page. Maximum 200. Ignored when replay_id is set, since all matching replay_id entries are returned in a single page.

page_tokenstringoptionalOpaque pagination cursor from a previous response's next_page_token. Mutually exclusive with replay_id.

replay_idarrayoptionalOne or more specific replays to fetch, each formatted as 'device_id/session_id', up to 100 values. Mutually exclusive with amplitude_id and page_token. When set, page_size is ignored and the response's next_page_token is always null.

sort_orderstringoptionalSort order for results by replay start time.

start_timestringoptionalLower bound (ISO 8601) on replay start time — only return replays that started at or after this time.

amplitudeanalytics_list_user_deletion_jobs#List Amplitude user-deletion jobs submitted within a date range. The start_day-end_day range cannot exceed 6 months. Returns an array of job objects, each with day, status (Staging, Submitted, or Done), amplitude_ids (the Amplitude user IDs in that day's job), app, and active_scrub_done_date.2 params▾

List Amplitude user-deletion jobs submitted within a date range. The start_day-end_day range cannot exceed 6 months. Returns an array of job objects, each with day, status (Staging, Submitted, or Done), amplitude_ids (the Amplitude user IDs in that day's job), app, and active_scrub_done_date.

NameTypeRequiredDescription

end_daystringrequiredEnd of the date range to list deletion jobs for, in YYYY-MM-DD format. The start_day-end_day range cannot exceed 6 months.

start_daystringrequiredStart of the date range to list deletion jobs for, in YYYY-MM-DD format.

amplitudeanalytics_list_user_properties#List user properties in Amplitude's taxonomy, optionally including previously deleted ones.1 param▾

List user properties in Amplitude's taxonomy, optionally including previously deleted ones.

NameTypeRequiredDescription

show_deletedbooleanoptionalWhether to include previously deleted user properties in the results.

amplitudeanalytics_remove_user_from_deletion#Remove a single user from a pending Amplitude user-deletion job before it locks, preventing their data from being deleted. This is a protective/cancel action, not a destructive one. It only works while the job is still in Staging status (within the roughly 3-day window after amplitudeanalytics_submit_user_deletion); once the job's status has flipped to Submitted, it is too late and this call has no effect. Use amplitudeanalytics_list_user_deletion_jobs to confirm a job's current status and day before calling this.2 params▾

Remove a single user from a pending Amplitude user-deletion job before it locks, preventing their data from being deleted. This is a protective/cancel action, not a destructive one. It only works while the job is still in Staging status (within the roughly 3-day window after amplitudeanalytics_submit_user_deletion); once the job's status has flipped to Submitted, it is too late and this call has no effect. Use amplitudeanalytics_list_user_deletion_jobs to confirm a job's current status and day before calling this.

NameTypeRequiredDescription

amplitude_idintegerrequiredThe Amplitude user ID to remove from the pending deletion job.

job_daystringrequiredThe deletion job's day, in YYYY-MM-DD format — the same day used when the job was originally submitted (see amplitudeanalytics_list_user_deletion_jobs).

amplitudeanalytics_request_cohort_membership#Start an asynchronous export of an Amplitude cohort's membership (the users/devices in the cohort). Returns a request_id — poll amplitudeanalytics_get_cohort_membership_status with that id until it reports completion, then call amplitudeanalytics_get_cohort_membership_file to download the data. Each call starts a NEW export job, so this is not idempotent even though it uses GET. CONFIRMED (live-tested): routing, auth, and path-templating all work correctly — a nonexistent cohort_id gets a bare 404 from Amplitude (not a JSON error body, unlike most other endpoints in this connector; this appears to be how this specific /api/5/cohorts/request/:id endpoint behaves for an unknown cohort, not a connector-side issue).3 params▾

Start an asynchronous export of an Amplitude cohort's membership (the users/devices in the cohort). Returns a request_id — poll amplitudeanalytics_get_cohort_membership_status with that id until it reports completion, then call amplitudeanalytics_get_cohort_membership_file to download the data. Each call starts a NEW export job, so this is not idempotent even though it uses GET. CONFIRMED (live-tested): routing, auth, and path-templating all work correctly — a nonexistent cohort_id gets a bare 404 from Amplitude (not a JSON error body, unlike most other endpoints in this connector; this appears to be how this specific /api/5/cohorts/request/:id endpoint behaves for an unknown cohort, not a connector-side issue).

NameTypeRequiredDescription

cohort_idstringrequiredThe Amplitude cohort id to export membership for. Find it via amplitudeanalytics_list_cohorts.

include_user_propertiesintegeroptionalSet to 1 to include each member's user properties in the exported file, 0 to export identifiers only. Amplitude expects the literal integer 0 or 1, not a boolean. Defaults to 0.

property_keysarrayoptionalSpecific user property names to include in the export, only used when include_user_properties is 1. Omit to include all user properties.

amplitudeanalytics_restore_event_property#Restore a previously deleted event property back to active status. CONFIRMED (live-tested): this only works for properties that were 'live' (actually seen on ingested events) before being soft-deleted. For a purely taxonomy-declared property that was never ingested, amplitudeanalytics_delete_event_property removes it entirely rather than soft-deleting it (it also disappears from amplitudeanalytics_list_event_properties, not just from active view), so this restore call fails with 'Not found' — there is nothing left to restore. This mirrors the identical, separately-confirmed behavior of amplitudeanalytics_restore_event_type and amplitudeanalytics_restore_user_property.1 param▾

Restore a previously deleted event property back to active status. CONFIRMED (live-tested): this only works for properties that were 'live' (actually seen on ingested events) before being soft-deleted. For a purely taxonomy-declared property that was never ingested, amplitudeanalytics_delete_event_property removes it entirely rather than soft-deleting it (it also disappears from amplitudeanalytics_list_event_properties, not just from active view), so this restore call fails with 'Not found' — there is nothing left to restore. This mirrors the identical, separately-confirmed behavior of amplitudeanalytics_restore_event_type and amplitudeanalytics_restore_user_property.

NameTypeRequiredDescription

event_propertystringrequiredThe name of the previously deleted event property to restore.

amplitudeanalytics_restore_event_type#Restore a previously deleted event type back to active/tracked status. CONFIRMED (live-tested): this only works for event types that were 'live' (actually ingested) before being soft-deleted. For a purely taxonomy-declared 'planned' event type that was deleted with amplitudeanalytics_delete_event_type, deletion removes it from the plan entirely rather than soft-deleting it, so this restore call will fail with 'Not found' — there is nothing left to restore.1 param▾

Restore a previously deleted event type back to active/tracked status. CONFIRMED (live-tested): this only works for event types that were 'live' (actually ingested) before being soft-deleted. For a purely taxonomy-declared 'planned' event type that was deleted with amplitudeanalytics_delete_event_type, deletion removes it from the plan entirely rather than soft-deleting it, so this restore call will fail with 'Not found' — there is nothing left to restore.

NameTypeRequiredDescription

event_typestringrequiredThe name of the deleted event type to restore.

amplitudeanalytics_restore_user_property#Restore a previously deleted user property back to active status. CONFIRMED (live-tested): this only works for properties that were 'live' (actually seen on ingested events) before being soft-deleted. For a purely taxonomy-declared property that was never ingested, amplitudeanalytics_delete_user_property removes it entirely rather than soft-deleting it, so this restore call fails with 'Not found' — there is nothing left to restore. This mirrors the identical, separately-confirmed behavior of amplitudeanalytics_restore_event_type and amplitudeanalytics_restore_event_property.1 param▾

Restore a previously deleted user property back to active status. CONFIRMED (live-tested): this only works for properties that were 'live' (actually seen on ingested events) before being soft-deleted. For a purely taxonomy-declared property that was never ingested, amplitudeanalytics_delete_user_property removes it entirely rather than soft-deleting it, so this restore call fails with 'Not found' — there is nothing left to restore. This mirrors the identical, separately-confirmed behavior of amplitudeanalytics_restore_event_type and amplitudeanalytics_restore_event_property.

NameTypeRequiredDescription

user_propertystringrequiredThe name of the previously deleted user property to restore.

amplitudeanalytics_submit_user_deletion#Submit a batch job to permanently delete users' data from Amplitude. Provide amplitude_ids, user_ids, or both — at least one is required; the API rejects a request with neither, which this input schema cannot enforce on its own. A single request accepts a maximum of 100 IDs combined across both fields. WARNING: this permanently deletes all of the specified user(s)' data from Amplitude, including backup/recovery systems. There is a roughly 3-day 'staging' window during which amplitudeanalytics_remove_user_from_deletion can still cancel/remove a user from this job; once the job status flips from staging to submitted (after that window), the deletion CANNOT be stopped. A deleted user who later sends new events will simply be recreated as a new user — deletion does not block future tracking.6 params▾

Submit a batch job to permanently delete users' data from Amplitude. Provide amplitude_ids, user_ids, or both — at least one is required; the API rejects a request with neither, which this input schema cannot enforce on its own. A single request accepts a maximum of 100 IDs combined across both fields. WARNING: this permanently deletes all of the specified user(s)' data from Amplitude, including backup/recovery systems. There is a roughly 3-day 'staging' window during which amplitudeanalytics_remove_user_from_deletion can still cancel/remove a user from this job; once the job status flips from staging to submitted (after that window), the deletion CANNOT be stopped. A deleted user who later sends new events will simply be recreated as a new user — deletion does not block future tracking.

NameTypeRequiredDescription

amplitude_idsarrayoptionalAmplitude IDs of the users to permanently delete. At least one of amplitude_ids or user_ids is required.

delete_from_orgbooleanoptionalIf true, deletes the user(s) from every project in the Amplitude organization instead of only the project tied to the connected account's credentials. Defaults to false.

ignore_invalid_idbooleanoptionalIf true, invalid or unrecognized IDs in the request are ignored instead of failing the whole request. Note the singular _id in this field name — Amplitude's documented field for this v1 API, distinct from a different, unrelated v2 API that uses the plural ignore_invalid_ids spelling. Defaults to false.

include_mapped_user_idsbooleanoptionalIf true, also deletes data for any additional user IDs merged/mapped to the specified users via Amplitude's User Mapping (aliasing) API. Defaults to false.

requesterstringoptionalEmail or identifier of the person requesting this deletion, recorded in Amplitude's audit trail for the job.

user_idsarrayoptionalYour application's user IDs of the users to permanently delete. At least one of amplitude_ids or user_ids is required.

amplitudeanalytics_update_annotation#Partially update an existing chart annotation. Only the fields you provide are changed; omitted fields keep their current value. Set chart_id to null to make a chart-scoped annotation global again. KNOWN AMPLITUDE API BUG (live-tested): setting end to null does NOT clear the end date, despite Amplitude's own documentation stating it should — the request is sent correctly and the call succeeds, but the annotation retains its previous end value. Other fields (e.g. details) update correctly in the same call, so this is isolated to end specifically. chart_id and category are both validated against real charts/categories in the project — an unknown value 404s rather than being accepted as free text.7 params▾

Partially update an existing chart annotation. Only the fields you provide are changed; omitted fields keep their current value. Set chart_id to null to make a chart-scoped annotation global again. KNOWN AMPLITUDE API BUG (live-tested): setting end to null does NOT clear the end date, despite Amplitude's own documentation stating it should — the request is sent correctly and the call succeeds, but the annotation retains its previous end value. Other fields (e.g. details) update correctly in the same call, so this is isolated to end specifically. chart_id and category are both validated against real charts/categories in the project — an unknown value 404s rather than being accepted as free text.

NameTypeRequiredDescription

annotation_idintegerrequiredThe ID of the annotation to update.

categorystringoptionalNew category name for this annotation.

chart_idstringoptionalNew chart to scope this annotation to. Set explicitly to null to make it global again.

detailsstringoptionalNew free-text details.

endstringoptionalNew end time, ISO 8601. Amplitude's docs say setting this explicitly to null removes the end time, but this was live-tested and CONFIRMED NOT TO WORK — the annotation keeps its previous end value regardless. This is an Amplitude API-side limitation, not a mapping bug (the null value is sent correctly).

labelstringoptionalNew label for the annotation.

startstringoptionalNew start time, ISO 8601.

amplitudeanalytics_update_annotation_category#Rename an existing chart annotation category.2 params▾

Rename an existing chart annotation category.

NameTypeRequiredDescription

categorystringrequiredThe new name for the category.

category_idintegerrequiredThe ID of the annotation category to rename.

amplitudeanalytics_update_cohort_membership#Add or remove individual members from an existing Amplitude cohort, without replacing the whole membership list. To create a cohort or replace its full membership list, use amplitudeanalytics_upload_cohort instead. CONFIRMED (live-tested): routing, auth, and the memberships array mapping all work correctly — a nonexistent cohort_id gets a clean, well-formed error: {"code":214,"message":"Cohort with id <id> not found"}.4 params▾

Add or remove individual members from an existing Amplitude cohort, without replacing the whole membership list. To create a cohort or replace its full membership list, use amplitudeanalytics_upload_cohort instead. CONFIRMED (live-tested): routing, auth, and the memberships array mapping all work correctly — a nonexistent cohort_id gets a clean, well-formed error: {"code":214,"message":"Cohort with id <id> not found"}.

NameTypeRequiredDescription

cohort_idstringrequiredThe id of the existing cohort to update. Find it via amplitudeanalytics_list_cohorts.

membershipsarrayrequiredArray of membership change objects. Each object must have: ids (array of strings — the user/group identifiers to add or remove), id_type ("BY_ID" or "BY_NAME"), and operation ("ADD" or "REMOVE"). Example: [{"ids":["user_123"],"id_type":"BY_ID","operation":"ADD"}].

count_groupstringoptionalThe count group this cohort tracks (e.g. "User" or a custom group name). Must match the cohort's existing count group. Defaults to "User".

skip_invalid_idsbooleanoptionalIf true, invalid IDs in the request are silently skipped. If false, the entire request is rejected if any ID is invalid. Defaults to true.

amplitudeanalytics_update_event_category#Rename an existing event category in Amplitude's taxonomy.2 params▾

Rename an existing event category in Amplitude's taxonomy.

NameTypeRequiredDescription

category_idstringrequiredThe id of the event category to rename, as used in the Amplitude Taxonomy API path. Treated as an opaque string identifier (not necessarily numeric), unlike the category_name used by amplitudeanalytics_get_event_category.

category_namestringrequiredThe new name for the category.

amplitudeanalytics_update_event_property#Partially update an existing event property in Amplitude's taxonomy. Only the fields you provide are changed; omitted fields keep their current value. Use overrideScope to control whether the update applies to an event-specific override or the shared property definition, and new_event_property_value to rename the property.12 params▾

Partially update an existing event property in Amplitude's taxonomy. Only the fields you provide are changed; omitted fields keep their current value. Use overrideScope to control whether the update applies to an event-specific override or the shared property definition, and new_event_property_value to rename the property.

NameTypeRequiredDescription

event_propertystringrequiredThe current name of the event property to update.

classificationsstringoptionalNew comma-separated classification tags for this property, from: PII, SENSITIVE, REVENUE. Only valid on shared properties — setting this on an event-specific override returns an error.

descriptionstringoptionalNew description for this property. Leave unset to keep the current description.

enum_valuesstringoptionalNew comma-separated list of allowed values. Only valid when type is 'enum'.

event_typestringoptionalNew event type to scope this property to.

is_array_typebooleanoptionalNew value for whether this property's values are an array of the given type.

is_hiddenbooleanoptionalNew value for whether this property is hidden from the Amplitude UI. Only settable on already-ingested properties.

is_requiredbooleanoptionalNew value for whether this property is required to be present on every event occurrence.

new_event_property_valuestringoptionalRenames the property to this new name. Leave unset to keep the current name.

overrideScopestringoptionalWhether this update applies to the event-specific override or the shared property definition.

regexstringoptionalNew regular expression the property's values must match. Only valid when type is 'string'.

typestringoptionalNew data type for this property.

amplitudeanalytics_update_event_type#Partially update an existing event type in Amplitude's taxonomy. Only the fields you provide are changed; omitted fields keep their current value. Set new_event_type to rename the event type.12 params▾

Partially update an existing event type in Amplitude's taxonomy. Only the fields you provide are changed; omitted fields keep their current value. Set new_event_type to rename the event type.

NameTypeRequiredDescription

event_typestringrequiredThe name of the existing event type to update.

categorystringoptionalNew category name for this event type.

descriptionstringoptionalNew free-text description for this event type.

display_namestringoptionalNew human-readable display label for this event type.

is_activebooleanoptionalWhether the event type is active.

is_hidden_from_dropdownsbooleanoptionalWhether to hide this event type from dropdown selectors. CONFIRMED (live-tested): this took effect immediately on a purely taxonomy-declared event type that was never actually ingested — contrary to Amplitude's documented 'only settable on already-ingested event types' — and setting it true made amplitudeanalytics_get_event_type return 'Not found' for that event even though it remained fully visible in amplitudeanalytics_list_event_types.

is_hidden_from_pathfinderbooleanoptionalWhether to hide this event type from Pathfinder. Amplitude documents this as only settable on already-ingested event types; not independently verified (the sibling is_hidden_from_dropdowns field was confirmed to take effect immediately on a never-ingested event, contrary to its own equivalent documentation, so this one may behave the same way — unconfirmed).

is_hidden_from_persona_resultsbooleanoptionalWhether to hide this event type from Persona results. Amplitude documents this as only settable on already-ingested event types; not independently verified (the sibling is_hidden_from_dropdowns field was confirmed to take effect immediately on a never-ingested event, contrary to its own equivalent documentation, so this one may behave the same way — unconfirmed).

is_hidden_from_timelinebooleanoptionalWhether to hide this event type from Timeline. Amplitude documents this as only settable on already-ingested event types; not independently verified (the sibling is_hidden_from_dropdowns field was confirmed to take effect immediately on a never-ingested event, contrary to its own equivalent documentation, so this one may behave the same way — unconfirmed).

new_event_typestringoptionalNew name for the event type. Set this to rename it.

ownerstringoptionalNew owner identifier or email for this event type.

tagsstringoptionalNew comma-separated list of tags for this event type.

amplitudeanalytics_update_group_property#Partially update an existing Amplitude Taxonomy group property. Amplitude's update-group-property docs list no body fields at all beyond the path variable, so every field below — including group_type — is inferred by analogy with the create endpoint and the sibling event/user property taxonomy endpoints, not explicitly confirmed; an incorrect field is simply rejected with a 400, not destructive. Only the fields you provide are changed; omitted fields keep their current value.9 params▾

Partially update an existing Amplitude Taxonomy group property. Amplitude's update-group-property docs list no body fields at all beyond the path variable, so every field below — including group_type — is inferred by analogy with the create endpoint and the sibling event/user property taxonomy endpoints, not explicitly confirmed; an incorrect field is simply rejected with a 400, not destructive. Only the fields you provide are changed; omitted fields keep their current value.

NameTypeRequiredDescription

group_propertystringrequiredThe name of the group property to update.

classificationsstringoptionalNew classification tags for this property. INFERRED from the sibling event/user property taxonomy endpoints — Amplitude's update-group-property docs list no body fields at all; verify empirically before relying on it.

descriptionstringoptionalNew human-readable description for the property. INFERRED from the sibling event/user property taxonomy endpoints — Amplitude's update-group-property docs list no body fields at all; verify empirically before relying on it.

enum_valuesstringoptionalNew allowed values for this property when type is 'enum'. INFERRED from the sibling event/user property taxonomy endpoints, including the assumption that it's a plain string here rather than an array — Amplitude's update-group-property docs list no body fields at all; verify the exact expected format empirically.

group_typestringoptionalNew group type to move this property to (e.g. 'org', 'company'). Amplitude's update-group-property docs do not list this or any body field — inferred by analogy with the create endpoint; verify empirically before relying on it.

is_array_typebooleanoptionalWhether this property holds an array of values rather than a single value. INFERRED from the sibling event/user property taxonomy endpoints — Amplitude's update-group-property docs list no body fields at all; verify empirically before relying on it.

is_hiddenbooleanoptionalWhether this property is hidden from Amplitude's UI pickers. INFERRED from the sibling event/user property taxonomy endpoints — Amplitude's update-group-property docs list no body fields at all; verify empirically before relying on it.

regexstringoptionalNew regular expression that values of this property must match. INFERRED from the sibling event/user property taxonomy endpoints — Amplitude's update-group-property docs list no body fields at all; verify empirically before relying on it.

typestringoptionalNew data type for this property. INFERRED from the sibling event/user property taxonomy endpoints — Amplitude's update-group-property docs list no body fields at all; verify empirically before relying on it.

amplitudeanalytics_update_user_property#Partially update an existing user property in Amplitude's taxonomy. Only the fields you provide are changed; omitted fields keep their current value. CONFIRMED BUG (live-tested, reproduced independently twice): new_event_property_value does NOT actually rename a user property — the call returns success:true, but the property keeps its original name unchanged and no property exists under the new name, verified via direct lookups both immediately after and via list. This is despite Amplitude's own documentation claiming this field renames both event and user properties; it works correctly for event properties (amplitudeanalytics_update_event_property) but is a silent no-op for user properties. Do not rely on this field to rename a user property — there is currently no working way to rename one through this API.10 params▾

Partially update an existing user property in Amplitude's taxonomy. Only the fields you provide are changed; omitted fields keep their current value. CONFIRMED BUG (live-tested, reproduced independently twice): new_event_property_value does NOT actually rename a user property — the call returns success:true, but the property keeps its original name unchanged and no property exists under the new name, verified via direct lookups both immediately after and via list. This is despite Amplitude's own documentation claiming this field renames both event and user properties; it works correctly for event properties (amplitudeanalytics_update_event_property) but is a silent no-op for user properties. Do not rely on this field to rename a user property — there is currently no working way to rename one through this API.

NameTypeRequiredDescription

user_propertystringrequiredThe current name of the user property to update. Per Amplitude's documentation, custom user properties may need a 'gp:' prefix in this identifier.

classificationsstringoptionalNew comma-separated classification tags for this property, from: PII, SENSITIVE, REVENUE.

descriptionstringoptionalNew description for this property. Leave unset to keep the current description.

enum_valuesstringoptionalNew comma-separated list of allowed values. Only valid when type is 'enum'.

is_array_typebooleanoptionalNew value for whether this property's values are an array of the given type.

is_hiddenbooleanoptionalNew value for whether this property is hidden from the Amplitude UI.

new_event_property_valuestringoptionalDocumented to rename the property to this new name, but CONFIRMED (live-tested) to be a silent no-op for user properties: the call succeeds with no error, yet the property keeps its original name and no property exists under the new name. There is currently no working way to rename a user property through this API.

overrideScopestringoptionalWhether this update applies to the event-specific override or the shared property definition.

regexstringoptionalNew regular expression the property's values must match. Only valid when type is 'string'.

typestringoptionalNew data type for this property.

amplitudeanalytics_upload_cohort#Create a new Amplitude behavioral cohort from an explicit list of user or Amplitude IDs, or update an existing cohort's membership list wholesale by passing existing_cohort_id. To add/remove individual members from an already-created cohort instead, use amplitudeanalytics_update_cohort_membership. CONFIRMED (live-tested against a real project, App ID and real non-dry-run save attempt, not just skip_save): every id in ids is validated against Amplitude's actual known-users table before any save happens — IDs with zero tracked activity in the project are rejected with error code 120 ("User id is invalid") or 110 ("Amplitude id is invalid"), reporting {matched, totals, invalid_ids_sample}. This rejection happens even with skip_invalid_ids: true when 100% of the provided IDs are invalid (there's nothing left to keep) — skip_invalid_ids only helps when the ids list is a genuine mix of valid and invalid entries. There is no way to create a cohort from IDs that have no real tracked history in the project.10 params▾

Create a new Amplitude behavioral cohort from an explicit list of user or Amplitude IDs, or update an existing cohort's membership list wholesale by passing existing_cohort_id. To add/remove individual members from an already-created cohort instead, use amplitudeanalytics_update_cohort_membership. CONFIRMED (live-tested against a real project, App ID and real non-dry-run save attempt, not just skip_save): every id in ids is validated against Amplitude's actual known-users table before any save happens — IDs with zero tracked activity in the project are rejected with error code 120 ("User id is invalid") or 110 ("Amplitude id is invalid"), reporting {matched, totals, invalid_ids_sample}. This rejection happens even with skip_invalid_ids: true when 100% of the provided IDs are invalid (there's nothing left to keep) — skip_invalid_ids only helps when the ids list is a genuine mix of valid and invalid entries. There is no way to create a cohort from IDs that have no real tracked history in the project.

NameTypeRequiredDescription

app_idintegerrequiredThe Amplitude project id that will contain the cohort.

id_typestringrequiredThe type of identifier used in the ids list: BY_AMP_ID (Amplitude IDs) or BY_USER_ID (your own user IDs).

idsarrayrequiredOne or more user or Amplitude IDs to include in the cohort, matching the type set in id_type. CONFIRMED: each ID must already have real tracked activity in the Amplitude project — Amplitude validates against its known-users table and rejects (error 120/110) any ID it has never seen, even a syntactically valid-looking one.

namestringrequiredDisplay name for the new cohort.

ownerstringrequiredLogin email of the Amplitude user who will own this cohort.

publishedbooleanrequiredIf true, the cohort is discoverable by other users in the Amplitude project. If false, it's hidden.

cohort_groupstringoptionalName of an existing group to base the cohort on, if creating a group-based cohort rather than a user-based one.

existing_cohort_idstringoptionalIf set, replaces this existing cohort's membership list instead of creating a new cohort.

skip_invalid_idsbooleanoptionalIf true, invalid IDs are silently skipped and the cohort is created from the remaining valid ones. If false, the entire request is rejected if any ID is invalid. Defaults to true. CONFIRMED: this only helps with a genuine mix of valid and invalid IDs — if every ID in the list is invalid (0 matched), the request is rejected regardless of this setting, since there would be nothing left to build the cohort from.

skip_savebooleanoptionalIf true, validates the request without actually saving the cohort — useful for a dry run. Defaults to false.