# Amplitude

Amplitude is a product analytics platform that helps teams understand user behavior, track engagement, and measure retention. The Sling Amplitude connector extracts data from the Amplitude REST API, supporting behavioral cohorts, chart annotations, event metadata, time-series metrics like active users and session length, and raw event export.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `api_key` **(required)** -> Your Amplitude project API Key
* `secret_key` **(required)** -> Your Amplitude project Secret Key

**Inputs (optional):**

* `anchor_date` -> Starting date for first sync of time-series endpoints (default: 1 year ago). Format: `YYYY-MM-DD`
* `base_url` -> Override the base URL (defaults to `https://amplitude.com`)

### Getting Your Credentials

1. Log in to your [Amplitude account](https://analytics.amplitude.com/)
2. Go to **Settings** (gear icon) → **Organization settings** → **Projects**
3. Click on your project name
4. You will see the **API Key** and **Secret Key** on the project settings page
5. Copy both values

{% hint style="warning" %}
**Important:** The API Key and Secret Key are used together for HTTP Basic authentication. Keep your Secret Key secure and never share it publicly.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set AMPLITUDE type=api spec=amplitude secrets='{ api_key: "your_api_key", secret_key: "your_secret_key" }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export AMPLITUDE='{ type: api, spec: amplitude, secrets: { api_key: "your_api_key", secret_key: "your_secret_key" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  AMPLITUDE:
    type: api
    spec: amplitude
    secrets:
      api_key: "your_api_key"
      secret_key: "your_secret_key"
```

**With anchor date for historical data:**

```yaml
connections:
  AMPLITUDE:
    type: api
    spec: amplitude
    secrets:
      api_key: "your_api_key"
      secret_key: "your_secret_key"
    inputs:
      anchor_date: "2024-01-01"
```

## Replication

Here's an example replication configuration to sync Amplitude data to a PostgreSQL database:

```yaml
source: AMPLITUDE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: amplitude.{stream_name}

streams:
  # Metadata endpoints
  cohorts:
  annotations:
  events_list:

  # Time-series metrics (incremental)
  active_users:
    mode: incremental
  average_session_length:
    mode: incremental

  # Raw event export (incremental)
  export:
    mode: incremental
    primary_key: [uuid]
    update_key: server_upload_time
```

**Full refresh for all endpoints:**

```yaml
source: AMPLITUDE
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: amplitude.{stream_name}

streams:
  cohorts:
  annotations:
  events_list:
  active_users:
  average_session_length:
  export:
```

## Endpoints

### Metadata & Catalog

| Endpoint      | Description                                 | Incremental |
| ------------- | ------------------------------------------- | ----------- |
| `cohorts`     | Behavioral cohort definitions               | No          |
| `annotations` | Chart annotations                           | No          |
| `events_list` | Active event types with current week totals | No          |

### Time-Series Metrics

| Endpoint                 | Description                              | Incremental |
| ------------------------ | ---------------------------------------- | ----------- |
| `active_users`           | Active and new user counts by day        | Yes         |
| `average_session_length` | Average session length in seconds by day | Yes         |

### Raw Event Export

| Endpoint | Description                                                         | Incremental |
| -------- | ------------------------------------------------------------------- | ----------- |
| `export` | Raw event data (all event properties, user properties, device info) | Yes         |

{% hint style="info" %}
The `export` endpoint returns raw event data in zipped JSON-lines format. Each record contains the full event payload including `event_type`, `event_properties`, `user_properties`, `device_id`, `session_id`, timestamps, and more. Data has a **2-hour latency** from the time events are received by Amplitude. Days with no events return no records (404 responses are handled gracefully).
{% endhint %}

To discover available endpoints:

```bash
sling conns discover AMPLITUDE
```

## Incremental Sync

The `active_users`, `average_session_length`, and `export` endpoints support incremental sync using date-based iteration:

* **First run:** Fetches data from the `anchor_date` (default: 1 year ago) up to yesterday (or 2 days ago for `export`, due to data latency)
* **Subsequent runs:** Only fetches data from the last synced date onward

For `active_users` and `average_session_length`, each day produces one record containing the time-series data for that date, with a `date` column added for tracking. For `export`, each day can produce many records — one per raw event — with `uuid` as the primary key and `server_upload_time` as the update key.

To customize the starting date:

```yaml
connections:
  AMPLITUDE:
    type: api
    spec: amplitude
    secrets:
      api_key: "..."
      secret_key: "..."
    inputs:
      anchor_date: "2024-06-01"
```

### Backfill

To backfill a specific date range, use the `range` source option:

```yaml
source: AMPLITUDE
target: MY_POSTGRES

defaults:
  object: amplitude.{stream_name}

streams:
  active_users:
    mode: incremental
    source_options:
      range: "2024-01-01,2024-06-30"
  export:
    mode: incremental
    primary_key: [uuid]
    update_key: server_upload_time
    source_options:
      range: "2024-01-01,2024-06-30"
```

## Rate Limiting

The Amplitude API enforces rate limits that vary by plan:

* **Free/Starter:** Limited API access
* **Growth/Enterprise:** Higher rate limits

The connector automatically:

* Uses conservative rate limiting (3–5 requests/second for most endpoints, 1 request/second for `export`)
* Processes time-series endpoints with concurrency of 3 (`export` uses concurrency of 1 due to larger payloads)
* Retries with exponential backoff on 429 (rate limit) responses
* Allows up to 5 retry attempts with a base backoff of 5 seconds

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/amplitude.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.