Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Amplitude Experiment Management

Scalekit connector
Open markdown

The Amplitude Experiment Management connector lets your AI agent act in each user's Amplitude Experiment Management account. Each user connects their own Amplitude Experiment Management access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 57 tools.

Tools
57
What they doRead · write · destructive
24 · 21 · 1224 read21 write12 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 Experiment Management connection

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

    Console steps with screenshots

    Register your Amplitude Experiment Management API key with Scalekit so it can authenticate and proxy requests on behalf of your users. This connector uses a Bearer token.

    1. Find your Amplitude Experiment data residency region

      Amplitude Experiment runs two separate data residency regions with different keys and API hosts. Before generating a key, confirm which region your project lives in:

      RegionAPI host
      US (default)experiment.amplitude.com
      EUexperiment.eu.amplitude.com

    2. Get your Management API key

      • Sign in to Amplitude and go to Experiment → Management API in the left sidebar.

      • Select the Project you want a key for.

      • Click Create key for project, or copy an existing key’s value from the list.

        Amplitude Experiment Management API page showing existing keys per project

    3. Create a connection in Scalekit

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

    4. Add a connected account

      Connected accounts link a specific user identifier in your system to a Management API 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, the Management API Key, and select the Data Residency Region that matches the key.
      • 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 'experiment.amplitude.com'
      await connectUser('amplitudeexperimentmanagement', 'user_123', {
        token: 'your-management-api-key',
        domain: 'experiment.amplitude.com',
      })
      

      // EU region
      await connectUser('amplitudeexperimentmanagement', 'user_123', {
        token: 'your-eu-management-api-key',
        domain: 'experiment.eu.amplitude.com',
      })

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'amplitudeexperimentmanagement'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Amplitude Experiment Management:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'amplitudeexperimentmanagement_list_all_versions',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Amplitude Experiment Management credentials there. If your app already has a user's credentials, add the account from your backend instead, as the console steps above show. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • amplitudeexperimentmanagement_get_experimentGet complete details for a single Amplitude experiment by its ID.Read-only

    Get Experiment

    Get complete details for a single Amplitude experiment by its ID. Returns the full experiment object — its shape is CONFIRMED via a live-tested list_experiments call against this org (list_experiments returns objects of this same type): id, projectId, deployments[], key, name, decision (nullable), decisionReason (nullable), description, enabled, evaluationMode (remote|local), bucketingKey, bucketingSalt, bucketingUnit, variants[] (richer than Amplitude's docs show — real shape is {key, payload: [{data: {mutations: [...]}, action: "mutate"}]}), rolledOutVariant (nullable), rolloutPercentage, rolloutWeights{}, targetSegments[], parentDependencies{} (optional, undocumented by Amplitude), stickyBucketing, state (no published enum — only "planning" and "running" appear in Amplitude's own examples, treat any other value as unconfirmed), startDate (nullable), endDate (nullable), experimentType (a-b-test|multi-arm-bandit), deliveryMethod (feature|web), deleted, tags[], createdBy, lastModifiedBy, createdAt, lastModifiedAt — plus two fields Amplitude's docs never mention at all: testInstrumentation (boolean) and version (number). Rate limit: 100 requests/second and 100,000/day, shared across the whole Experiment Management API (not per-endpoint). CONFIRMED (live-tested, reproduced 4x): this specific operation returns HTTP 403 "User does not have permission (experimentation)" for this connected account, even though list_experiments (no ID) and create_experiment both work fine with the same credentials. This looks like a role/permission scope on the Amplitude user tied to this Management API key, not an org-wide entitlement gate (contrast with the Profile API's different "org does not have access" 401) — check the Amplitude user's Experiment role/permissions if you hit this.

    Inputs

    idstringrequired
    The experiment's ID.
  • amplitudeexperimentmanagement_get_experiment_variantGet a single variant's details from an Amplitude experiment, by experiment ID and variant key (the variants[].key value, e.g.Read-only

    Get Experiment Variant

    Get a single variant's details from an Amplitude experiment, by experiment ID and variant key (the variants[].key value, e.g. "control" or "treatment"). Use list_experiment_variants or the parent experiment's variants[] array to find valid keys. Amplitude's docs give no example response JSON for this endpoint; expect the same variant object shape as list_experiment_variants — live-confirmed richer shape {key, payload: [{data: {mutations: [...]}, action: "mutate"}]}, versus the docs' bare {"key": "control"} illustration. Rate limit: 100 requests/second and 100,000/day, shared across the whole Experiment Management API (not per-endpoint). CONFIRMED (live-tested): this exact operation returned HTTP 403 "User does not have permission (experimentation)" when called against a real, pre-existing experiment's real variant, but returned a normal HTTP 400 "Variant key does not exist" (reaching real business logic, not a permission wall) when called against a nonexistent variant key on a different, freshly-created test experiment with the same credentials. This suggests the "experimentation" permission gate may be scoped per-experiment (e.g. by delivery method, ownership, or another per-object attribute) rather than being a blanket gate on this operation — the root cause isn't confirmed, only the discrepancy itself.

    Inputs

    idstringrequired
    The experiment's ID.
    variant_keystringrequired
    The variant's key.
  • amplitudeexperimentmanagement_get_experiment_variant_cohortsList the cohorts explicitly included in this experiment variant's targeting.Read-only

    Get Experiment Variant Cohorts

    List the cohorts explicitly included in this experiment variant's targeting. CONFIRMED from Amplitude's docs: GET /api/1/experiments/{id}/variants/{variantKey}/cohorts, no query parameters documented (no pagination). Response is 200 OK with an array of cohort ID strings (not objects), per Amplitude's docs. Rate limit: 100 requests/second and 100,000/day, shared across the whole Experiment Management API (not per-endpoint). CONFIRMED (live-tested): this exact operation returned HTTP 403 "User does not have permission (experimentation)" when called against a real, pre-existing experiment's real variant, but returned a normal HTTP 400 "Variant key does not exist" (reaching real business logic, not a permission wall) when called against a nonexistent variant key on a different, freshly-created test experiment with the same credentials. This suggests the "experimentation" permission gate may be scoped per-experiment (e.g. by delivery method, ownership, or another per-object attribute) rather than being a blanket gate on this operation — the root cause isn't confirmed, only the discrepancy itself.

    Inputs

    idstringrequired
    The experiment's ID.
    variant_keystringrequired
    The variant's key.
  • amplitudeexperimentmanagement_get_experiment_variant_usersList the users and devices explicitly force-bucketed into this experiment variant via inclusions — separate from, and in addition to, the experiment's normal allocation/targeting rules.Read-only

    Get Experiment Variant Users

    List the users and devices explicitly force-bucketed into this experiment variant via inclusions — separate from, and in addition to, the experiment's normal allocation/targeting rules. CONFIRMED from Amplitude's docs: GET /api/1/experiments/{id}/variants/{variantKey}/users, no query parameters documented (no pagination). Response is 200 OK with the variant's inclusions as an array of JSON objects; Amplitude's docs don't show a concrete example of what fields are on each object, so treat the inclusion object's shape as unconfirmed until you inspect a live response — the sibling 'remove users from variant' endpoint does confirm these are addressable by a zero-indexed userIndex, which is a useful hint about the response's ordering. Rate limit: 100 requests/second and 100,000/day, shared across the whole Experiment Management API (not per-endpoint). CONFIRMED (live-tested): this exact operation returned HTTP 403 "User does not have permission (experimentation)" when called against a real, pre-existing experiment's real variant, but returned a normal HTTP 400 "Variant key does not exist" (reaching real business logic, not a permission wall) when called against a nonexistent variant key on a different, freshly-created test experiment with the same credentials. This suggests the "experimentation" permission gate may be scoped per-experiment (e.g. by delivery method, ownership, or another per-object attribute) rather than being a blanket gate on this operation — the root cause isn't confirmed, only the discrepancy itself.

    Inputs

    idstringrequired
    The experiment's ID.
    variant_keystringrequired
    The variant's key.
  • amplitudeexperimentmanagement_get_experiment_versionGet a single historical version snapshot of an Amplitude experiment, by experiment ID and version ID.Read-only

    Get Experiment Version

    Get a single historical version snapshot of an Amplitude experiment, by experiment ID and version ID. Use a version ID returned from list_experiment_versions. Amplitude's docs describe this endpoint only as returning "details of a specific version of an experiment" — no example response JSON and no query parameters are documented, so the exact snapshot shape is UNCONFIRMED; expect it to mirror the experiment object's fields as they existed at that version, plus version metadata (e.g. version number, createdBy, createdAt). Rate limit: 100 requests/second and 100,000/day, shared across the whole Experiment Management API (not per-endpoint). CONFIRMED (live-tested): this exact operation returned HTTP 403 "User does not have permission (experimentation)" when called against a real, pre-existing experiment's real variant, but returned a normal HTTP 400 "Variant key does not exist" (reaching real business logic, not a permission wall) when called against a nonexistent variant key on a different, freshly-created test experiment with the same credentials. This suggests the "experimentation" permission gate may be scoped per-experiment (e.g. by delivery method, ownership, or another per-object attribute) rather than being a blanket gate on this operation — the root cause isn't confirmed, only the discrepancy itself.

    Inputs

    idstringrequired
    The experiment's ID.
    version_idstringrequired
    The version's ID, from a prior list_experiment_versions call.
  • amplitudeexperimentmanagement_get_flagGet the full configuration of a single Amplitude Experiment feature flag by its ID.Read-only

    Get Flag

    Get the full configuration of a single Amplitude Experiment feature flag by its ID. Returns the flag's complete details as documented by Amplitude: id, projectId, deployments, key, name, description, enabled, evaluationMode, bucketingKey, bucketingSalt, bucketingUnit, variants, rolloutPercentage, rolloutWeights, targetSegments, deleted, tags, createdBy, lastModifiedBy, createdAt, and lastModifiedAt (timestamps in UTC ISO 8601). This org has confirmed Feature Experimentation entitlement (verified via live-tested List Flags and List Experiments calls against this same API), so this endpoint should not hit entitlement-gating errors. UNCONFIRMED: whether parentDependencies appears in this specific endpoint's response — Amplitude's docs for this endpoint don't show a full example response body, so its presence/shape here is inferred from the general flag object schema rather than directly observed. Rate limit: 100 requests/second and 100,000/day, shared across the whole Experiment Management API (not per-endpoint).

    Inputs

    idstringrequired
    The flag's ID, as shown in the Amplitude app URL for the flag.
  • amplitudeexperimentmanagement_get_flag_variantGet a single variant's details from an Amplitude Experiment feature flag.Read-only

    Get Flag Variant

    Get a single variant's details from an Amplitude Experiment feature flag. Returns a JSON object with key (required), and optional payload, name, and description fields. Variant keys may contain letters, numbers, underscores, and hyphens (per Amplitude's docs). This org has confirmed Feature Experimentation entitlement (verified via live-tested List Flags and List Experiments calls). Rate limit: 100 requests/second and 100,000/day, shared across the whole Experiment Management API (not per-endpoint).

    Inputs

    idstringrequired
    The flag's ID, as shown in the Amplitude app URL for the flag.
    variant_keystringrequired
    The variant's key. May contain letters, numbers, underscores, and hyphens.
  • amplitudeexperimentmanagement_get_flag_variant_cohortsList the cohorts individually assigned (included) to a specific variant of an Amplitude Experiment feature flag.Read-only

    Get Flag Variant Cohorts

    List the cohorts individually assigned (included) to a specific variant of an Amplitude Experiment feature flag. No query parameters, filters, or pagination are documented for this endpoint. Per Amplitude's docs, a successful call returns a 200 OK response with "the variant's cohort inclusions as an array of cohort IDs" — a flat array of ID strings. No literal example response body is published, but the docs are explicit that the array holds cohort IDs directly (unlike the sibling Get Flag Variant Users endpoint, whose array-of-JSON-objects shape is not documented in detail). CONFIRMED (live-tested): this org has Feature Experimentation entitlement. Rate limit: 100 requests/second and 100,000/day, shared across the whole Experiment Management API (not per-endpoint).

    Inputs

    idstringrequired
    The flag's ID (not its key) — find it in the URL of the flag's page in the Amplitude app.
    variant_keystringrequired
    The key of the variant to fetch cohort inclusions for.
All 121 in Analytics