> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Amplitude Integration for AI Agents & Workflows

> Track events, identify users and groups, search for users, query analytics, and retrieve revenue data from Amplitude

{/* Self-hosted logo — build-time vendored from modulex.json / Iconify (see scripts/lib/logo.js). */}

<img src="https://mintcdn.com/modulexaillc/zKB2qsP6Q61VNLfB/logos/amplitude.svg?fit=max&auto=format&n=zKB2qsP6Q61VNLfB&q=85&s=28e6774e25ca90f870f1a5d7dfac787c" alt="Amplitude logo" width="72" height="72" data-path="logos/amplitude.svg" />

## Overview

Add **Amplitude** to any ModuleX agent or workflow. Track events, identify users and groups, search for users, query analytics, and retrieve revenue data from Amplitude via its HTTP V2, Identify, Dashboard REST, and User Profile APIs.

<Info>
  **Categories**: Analytics & Data · Product Analytics · Marketing · **Auth**: Amplitude API Key + Secret Key · **Actions**: 11
</Info>

## Authentication

### Amplitude API Key + Secret Key

Authenticate with your Amplitude project's API Key (used to send events and identify users) and Secret Key (required for the Dashboard REST API and User Profile analytics endpoints).

<Steps>
  <Step title="Step 1">
    Sign in to Amplitude and open the project you want to use.
  </Step>

  <Step title="Step 2">
    Go to Settings -> Projects -> (your project) -> General.
  </Step>

  <Step title="Step 3">
    Copy the 'API Key' and the 'Secret Key' shown for the project.
  </Step>

  <Step title="Step 4">
    Provide the API Key for event tracking; the Secret Key is also needed for analytics/dashboard queries.
  </Step>
</Steps>

#### Required Credentials

| Field      | Description                                                                              | Required | Format |
| ---------- | ---------------------------------------------------------------------------------------- | -------- | ------ |
| API Key    | Amplitude project API Key (used for event tracking and Dashboard Basic auth).            | Yes      | `-`    |
| Secret Key | Amplitude project Secret Key (required for Dashboard REST API and User Profile queries). | No       | `-`    |

## Available Actions

<AccordionGroup>
  <Accordion title="send_event — Track an event in Amplitude using the HTTP V2 API.">
    ### Parameters

    <ResponseField name="event_type" type="string" required>
      Name of the event (e.g., "page\_view", "purchase").
    </ResponseField>

    <ResponseField name="user_id" type="string">
      User ID (required if no device\_id).
    </ResponseField>

    <ResponseField name="device_id" type="string">
      Device ID (required if no user\_id).
    </ResponseField>

    <ResponseField name="event_properties" type="object">
      Custom event properties as a JSON object.
    </ResponseField>

    <ResponseField name="user_properties" type="object">
      User properties to set (supports $set, $setOnce, $add, $append, \$unset).
    </ResponseField>

    <ResponseField name="time" type="integer">
      Event timestamp in milliseconds since epoch.
    </ResponseField>

    <ResponseField name="session_id" type="integer">
      Session start time in milliseconds since epoch (-1 for no session).
    </ResponseField>

    <ResponseField name="insert_id" type="string">
      Unique ID for deduplication (within a 7-day window).
    </ResponseField>

    <ResponseField name="app_version" type="string">
      Application version string.
    </ResponseField>

    <ResponseField name="platform" type="string">
      Platform (e.g., "Web", "iOS", "Android").
    </ResponseField>

    <ResponseField name="country" type="string">
      Two-letter country code.
    </ResponseField>

    <ResponseField name="language" type="string">
      Language code (e.g., "en").
    </ResponseField>

    <ResponseField name="ip" type="string">
      IP address for geo-location (use "\$remote" for request IP).
    </ResponseField>

    <ResponseField name="price" type="number">
      Price of the item purchased.
    </ResponseField>

    <ResponseField name="quantity" type="integer">
      Quantity of items purchased.
    </ResponseField>

    <ResponseField name="revenue" type="number">
      Revenue amount.
    </ResponseField>

    <ResponseField name="product_id" type="string">
      Product identifier.
    </ResponseField>

    <ResponseField name="revenue_type" type="string">
      Revenue type (e.g., "purchase", "refund").
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "code": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Code"
        },
        "events_ingested": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Events Ingested"
        },
        "payload_size_bytes": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Payload Size Bytes"
        },
        "server_upload_time": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Server Upload Time"
        }
      },
      "required": [
        "success"
      ],
      "title": "SendEventOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="identify_user — Set user properties in Amplitude using the Identify API. Supports $set, $setOnce, $add, $append, $unset operations.">
    ### Parameters

    <ResponseField name="user_properties" type="object" required>
      User properties to set. Use operations like $set, $setOnce, $add, $append, \$unset.
    </ResponseField>

    <ResponseField name="user_id" type="string">
      User ID (required if no device\_id).
    </ResponseField>

    <ResponseField name="device_id" type="string">
      Device ID (required if no user\_id).
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "code": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Code"
        },
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Message"
        }
      },
      "required": [
        "success"
      ],
      "title": "IdentifyUserOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="group_identify — Set group-level properties in Amplitude. Supports $set, $setOnce, $add, $append, $unset operations.">
    ### Parameters

    <ResponseField name="group_type" type="string" required>
      Group classification (e.g., "company", "org\_id").
    </ResponseField>

    <ResponseField name="group_value" type="string" required>
      Specific group identifier (e.g., "Acme Corp").
    </ResponseField>

    <ResponseField name="group_properties" type="object" required>
      Group properties as a JSON object. Use operations like $set, $setOnce, $add, $append, \$unset.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "code": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Code"
        },
        "message": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Message"
        }
      },
      "required": [
        "success"
      ],
      "title": "GroupIdentifyOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="user_search — Search for a user by User ID, Device ID, or Amplitude ID using the Dashboard REST API.">
    ### Parameters

    <ResponseField name="user" type="string" required>
      User ID, Device ID, or Amplitude ID to search for.
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "UserSearchMatch": {
          "additionalProperties": false,
          "description": "A single user-search match entry.",
          "properties": {
            "amplitude_id": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Amplitude Id"
            },
            "user_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "User Id"
            }
          },
          "title": "UserSearchMatch",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "matches": {
          "items": {
            "$ref": "#/$defs/UserSearchMatch"
          },
          "title": "Matches",
          "type": "array"
        },
        "type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Type"
        }
      },
      "required": [
        "success"
      ],
      "title": "UserSearchOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="user_activity — Get the event stream for a specific user by their Amplitude ID.">
    ### Parameters

    <ResponseField name="amplitude_id" type="string" required>
      Amplitude internal user ID.
    </ResponseField>

    <ResponseField name="offset" type="integer">
      Offset for pagination (default 0).
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Maximum number of events to return (default 1000, max 1000).
    </ResponseField>

    <ResponseField name="direction" type="string">
      Sort direction: "latest" or "earliest" (default: latest).
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "$defs": {
        "UserActivityEvent": {
          "additionalProperties": false,
          "description": "A single event in a user's activity stream.",
          "properties": {
            "event_type": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Event Type"
            },
            "event_time": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Event Time"
            },
            "event_properties": {
              "additionalProperties": true,
              "title": "Event Properties",
              "type": "object"
            },
            "user_properties": {
              "additionalProperties": true,
              "title": "User Properties",
              "type": "object"
            },
            "session_id": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Session Id"
            },
            "platform": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Platform"
            },
            "country": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Country"
            },
            "city": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "City"
            }
          },
          "title": "UserActivityEvent",
          "type": "object"
        },
        "UserData": {
          "additionalProperties": false,
          "description": "User metadata returned alongside an activity stream.",
          "properties": {
            "user_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "User Id"
            },
            "canonical_amplitude_id": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Canonical Amplitude Id"
            },
            "num_events": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Num Events"
            },
            "num_sessions": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Num Sessions"
            },
            "platform": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Platform"
            },
            "country": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Country"
            }
          },
          "title": "UserData",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "events": {
          "items": {
            "$ref": "#/$defs/UserActivityEvent"
          },
          "title": "Events",
          "type": "array"
        },
        "user_data": {
          "anyOf": [
            {
              "$ref": "#/$defs/UserData"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "required": [
        "success"
      ],
      "title": "UserActivityOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="user_profile — Get a user profile including properties, cohort memberships, and computed properties.">
    ### Parameters

    <ResponseField name="user_id" type="string">
      External user ID (required if no device\_id).
    </ResponseField>

    <ResponseField name="device_id" type="string">
      Device ID (required if no user\_id).
    </ResponseField>

    <ResponseField name="get_amp_props" type="boolean">
      Include Amplitude user properties (default: false). (Default: `false`)
    </ResponseField>

    <ResponseField name="get_cohort_ids" type="boolean">
      Include cohort IDs the user belongs to (default: false). (Default: `false`)
    </ResponseField>

    <ResponseField name="get_computations" type="boolean">
      Include computed user properties (default: false). (Default: `false`)
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "user_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "User Id"
        },
        "device_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Device Id"
        },
        "amp_props": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Amp Props"
        },
        "cohort_ids": {
          "anyOf": [
            {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Cohort Ids"
        },
        "computations": {
          "anyOf": [
            {
              "additionalProperties": true,
              "type": "object"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Computations"
        }
      },
      "required": [
        "success"
      ],
      "title": "UserProfileOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="event_segmentation — Query event analytics data with segmentation. Get event counts, uniques, averages, and more.">
    ### Parameters

    <ResponseField name="event_type" type="string" required>
      Event type name to analyze.
    </ResponseField>

    <ResponseField name="start" type="string" required>
      Start date in YYYYMMDD format.
    </ResponseField>

    <ResponseField name="end" type="string" required>
      End date in YYYYMMDD format.
    </ResponseField>

    <ResponseField name="metric" type="string">
      Metric type: uniques, totals, pct\_dau, average, histogram, sums, value\_avg, or formula (default: uniques).
    </ResponseField>

    <ResponseField name="interval" type="string">
      Time interval: 1 (daily), 7 (weekly), or 30 (monthly).
    </ResponseField>

    <ResponseField name="group_by" type="string">
      Property name to group by (prefix custom user properties with "gp:").
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Maximum number of group-by values (max 1000).
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "series": {
          "items": {},
          "title": "Series",
          "type": "array"
        },
        "series_labels": {
          "items": {},
          "title": "Series Labels",
          "type": "array"
        },
        "series_collapsed": {
          "items": {},
          "title": "Series Collapsed",
          "type": "array"
        },
        "x_values": {
          "items": {
            "type": "string"
          },
          "title": "X Values",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "EventSegmentationOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_active_users — Get active or new user counts over a date range from the Dashboard REST API.">
    ### Parameters

    <ResponseField name="start" type="string" required>
      Start date in YYYYMMDD format.
    </ResponseField>

    <ResponseField name="end" type="string" required>
      End date in YYYYMMDD format.
    </ResponseField>

    <ResponseField name="metric" type="string">
      Metric type: "active" or "new" (default: active).
    </ResponseField>

    <ResponseField name="interval" type="string">
      Time interval: 1 (daily), 7 (weekly), or 30 (monthly).
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "series": {
          "items": {},
          "title": "Series",
          "type": "array"
        },
        "series_meta": {
          "items": {
            "type": "string"
          },
          "title": "Series Meta",
          "type": "array"
        },
        "x_values": {
          "items": {
            "type": "string"
          },
          "title": "X Values",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetActiveUsersOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="realtime_active_users — Get real-time active user counts at 5-minute granularity for the last 2 days.">
    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "series": {
          "items": {},
          "title": "Series",
          "type": "array"
        },
        "series_labels": {
          "items": {
            "type": "string"
          },
          "title": "Series Labels",
          "type": "array"
        },
        "x_values": {
          "items": {
            "type": "string"
          },
          "title": "X Values",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "RealtimeActiveUsersOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="list_events — List all event types in the project with their weekly totals and unique counts.">
    ### Response

    ```json theme={null}
    {
      "$defs": {
        "ProjectEvent": {
          "additionalProperties": false,
          "description": "A single event type listed for the project.",
          "properties": {
            "value": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Value"
            },
            "display_name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Display Name"
            },
            "totals": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Totals"
            },
            "hidden": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Hidden"
            },
            "deleted": {
              "anyOf": [
                {
                  "type": "boolean"
                },
                {
                  "type": "null"
                }
              ],
              "default": null,
              "title": "Deleted"
            }
          },
          "title": "ProjectEvent",
          "type": "object"
        }
      },
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "events": {
          "items": {
            "$ref": "#/$defs/ProjectEvent"
          },
          "title": "Events",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "ListEventsOutput",
      "type": "object"
    }
    ```
  </Accordion>

  <Accordion title="get_revenue — Get revenue LTV data including ARPU, ARPPU, total revenue, and paying user counts.">
    ### Parameters

    <ResponseField name="start" type="string" required>
      Start date in YYYYMMDD format.
    </ResponseField>

    <ResponseField name="end" type="string" required>
      End date in YYYYMMDD format.
    </ResponseField>

    <ResponseField name="metric" type="string">
      Metric: 0 (ARPU), 1 (ARPPU), 2 (Total Revenue), 3 (Paying Users).
    </ResponseField>

    <ResponseField name="interval" type="string">
      Time interval: 1 (daily), 7 (weekly), or 30 (monthly).
    </ResponseField>

    ### Response

    ```json theme={null}
    {
      "additionalProperties": false,
      "properties": {
        "success": {
          "title": "Success",
          "type": "boolean"
        },
        "error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null,
          "title": "Error"
        },
        "series": {
          "items": {},
          "title": "Series",
          "type": "array"
        },
        "series_labels": {
          "items": {
            "type": "string"
          },
          "title": "Series Labels",
          "type": "array"
        },
        "x_values": {
          "items": {
            "type": "string"
          },
          "title": "X Values",
          "type": "array"
        }
      },
      "required": [
        "success"
      ],
      "title": "GetRevenueOutput",
      "type": "object"
    }
    ```
  </Accordion>
</AccordionGroup>

## Limits & Quotas

* HTTP V2 ingestion: limit uploads to 100 batches/second and 1000 events/second.
* Dashboard REST API analytics endpoints are subject to per-project rate limits and cost thresholds.
* `user_activity` returns at most 1000 events per call (use `offset` to page).
* Error model: non-2xx responses (and missing credentials) are returned as `success=False` + `error` rather than raising.

## Related integrations

<CardGroup cols={3}>
  <Card title="Google Analytics" href="/integrations/tools/google-analytics" />

  <Card title="Google Tag Manager" href="/integrations/tools/google-tag-manager" />

  <Card title="Mixpanel" href="/integrations/tools/mixpanel" />
</CardGroup>

## Links

* [Amplitude](https://amplitude.com)