Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Amplitude Analytics

Scalekit connector
Open markdown

The Amplitude Analytics connector lets your AI agent act in each user's Amplitude Analytics account. Each user connects their own Amplitude Analytics API key and secret once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 74 tools.

Tools
74
What they doRead · write · destructive
43 · 23 · 843 read23 write8 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  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. Create the Amplitude Analytics connection

    In AgentKit > Connections, create an Amplitude Analytics connection. The name you give it is the connection_name your code passes. See Configure connections.

    Console steps with screenshots

    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:

      RegionAPI host
      US (default)amplitude.com
      EUanalytics.eu.amplitude.com

    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.

        Amplitude API and Secret Keys page showing the API Keys tab with a generated key

    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.

        Amplitude API and Secret Keys page showing the Secret Keys tab with a hidden secret key

    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 one in the dashboard to test. In production, each user adds their own through the authorization link: they enter their credentials on the page it opens.

      In the dashboard, to test

      • 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.

      From your backend, if your app already has the credentials

      For example, when users enter them on a settings page in your app:

      import { ConnectorStatus } from '@scalekit-sdk/node'
      

      // Upsert the account, then make sure it is ACTIVE before the first tool call.
      async function connectUser(connectionName, identifier, details) {
        const authorizationDetails = { details: { case: 'staticAuth', value: { details } } }
        let { connectedAccount } = await scalekit.actions.upsertConnectedAccount({
          connectionName,
          identifier,
          authorizationDetails,
        })
        if (connectedAccount?.status !== ConnectorStatus.ACTIVE) {
          ;({ connectedAccount } = await scalekit.actions.upsertConnectedAccount({
            connectionName,
            identifier,
            authorizationDetails,
          }))
        }
        return connectedAccount
      }
      

      // US region (default) — omit `domain` or set it to 'amplitude.com'
      await connectUser('amplitudeanalytics', 'user_123', {
        username: 'your-amplitude-api-key',
        password: 'your-amplitude-secret-key',
        domain: 'amplitude.com',
      })
      

      // EU region
      await connectUser('amplitudeanalytics', 'user_123', {
        username: 'your-eu-amplitude-api-key',
        password: 'your-eu-amplitude-secret-key',
        domain: 'analytics.eu.amplitude.com',
      })

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • amplitudeanalytics_export_eventsExport raw event data uploaded to Amplitude within a date range as a zip archive of NDJSON files.Read-only

    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.

    Inputs

    endstringrequired
    End of the export range, in YYYYMMDDTHH format (year, month, day, hour). The start-end range cannot exceed 365 days.
    startstringrequired
    Start of the export range, in YYYYMMDDTHH format (year, month, day, hour).
  • amplitudeanalytics_get_active_and_new_user_countsPull the Active/New User Counts chart from the Amplitude Dashboard REST API: count of active or new users per interval over a date range, with optional segment filters and a single group-by property.Read-only

    Get Active and New User Counts

    Pull the Active/New User Counts chart from the Amplitude Dashboard REST API: count of active or new users per interval over a date range, with optional segment filters and a single group-by property. Response shape: {"data": {"series": [[number,...]], "seriesMeta": [string,...], "xValues": ["YYYY-MM-DD",...]}}. Rate limits: 5 concurrent requests shared with other Amplitude Dashboard/Cohort API calls, up to 108,000 cost per hour.

    Inputs

    endstringrequired
    End date of the query range, format YYYYMMDD (e.g. 20260131).
    startstringrequired
    Start date of the query range, format YYYYMMDD (e.g. 20260101).
    group_bystring
    Property to group results by, e.g. gp:country. This endpoint supports only one group-by property.
    intervalinteger
    Time bucket size for the returned series: 1 (daily), 7 (weekly), or 30 (monthly). Defaults to 1.one of 1730default 1
    metricstring
    Which user count to compute: new (users first seen in each interval) or active (users active in each interval). Defaults to active.one of newactivedefault active
    segment_definitionsstring
    JSON-encoded array of segment definitions to split the count by cohort/property segments, e.g. [{"prop":"gp:country","op":"is","values":["US"]}].
  • amplitudeanalytics_get_annotationRetrieve a single chart annotation by its ID.Read-only

    Get Annotation

    Retrieve a single chart annotation by its ID.

    Inputs

    annotation_idintegerrequired
    The ID of the annotation to retrieve.
  • amplitudeanalytics_get_annotation_categoryRetrieve a single chart annotation category by its ID.Read-only

    Get Annotation Category

    Retrieve a single chart annotation category by its ID.

    Inputs

    category_idintegerrequired
    The ID of the annotation category to retrieve.
  • amplitudeanalytics_get_average_session_lengthPull the Average Session Length chart from the Amplitude Dashboard REST API: average session length in seconds for each day in the given date range.Read-only

    Get Average Session Length

    Pull the Average Session Length chart from the Amplitude Dashboard REST API: average session length in seconds for each day in the given date range. Response shape: {"data": {"series": [[number,...]], "seriesMeta": [{"segmentIndex": 0}], "xValues": ["YYYY-MM-DD",...]}}. Rate limits: 5 concurrent requests shared with other Amplitude Dashboard/Cohort API calls, up to 108,000 cost per hour.

    Inputs

    endstringrequired
    End date of the query range, format YYYYMMDD (e.g. 20260104).
    startstringrequired
    Start date of the query range, format YYYYMMDD (e.g. 20260101).
  • amplitudeanalytics_get_average_sessions_per_userPull the Average Sessions Per User chart from the Amplitude Dashboard REST API: average number of sessions per user for each day in the given date range.Read-only

    Get Average Sessions Per User

    Pull the Average Sessions Per User chart from the Amplitude Dashboard REST API: average number of sessions per user for each day in the given date range. Response shape: {"data": {"series": [[number,...]], "seriesMeta": [{"segmentIndex": 0}], "xValues": ["YYYY-MM-DD",...]}}. Rate limits: 5 concurrent requests shared with other Amplitude Dashboard/Cohort API calls, up to 108,000 cost per hour.

    Inputs

    endstringrequired
    End date of the query range, format YYYYMMDD (e.g. 20260104).
    startstringrequired
    Start date of the query range, format YYYYMMDD (e.g. 20260101).
  • amplitudeanalytics_get_chart_resultsGet results from any existing saved Amplitude chart by its chart ID, without having to know or replicate the chart's own query definition.Read-only

    Get Chart Results

    Get results from any existing saved Amplitude chart by its chart ID, without having to know or replicate the chart's own query definition. Find the chart_id in the chart's URL in the Amplitude web app, e.g. the 'abc123' segment in https://analytics.amplitude.com/yourorg/chart/abc123. Per Amplitude's docs, the response's exact shape varies by the chart's underlying type (event segmentation, funnel, retention, etc.) — expect a shape similar to the corresponding dedicated endpoint (e.g. amplitudeanalytics_get_event_segmentation's response shape for an Event Segmentation chart). Despite the path ending in /csv, Amplitude's own documentation confirms this returns JSON, not a CSV file. Rate limits: 5 concurrent requests shared with other Amplitude Dashboard/Cohort API calls, up to 108,000 cost per hour.

    Inputs

    chart_idstringrequired
    The ID of the saved chart to fetch results for, taken from the chart's URL in the Amplitude web app.
  • amplitudeanalytics_get_cohort_membership_fileDownload the completed cohort membership export started with amplitudeanalytics_request_cohort_membership, once amplitudeanalytics_get_cohort_membership_status reports it complete.Read-only

    Download 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.

    Inputs

    request_idstringrequired
    The 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.
All 109 in Analytics