> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/marketing/amplitude.md).

# Amplitude

Connect Amplitude user events, sessions, and analytics to Google Sheets, BigQuery, or BI tools via Coupler.io without manual exports.

Amplitude is a product analytics platform that tracks user behavior, session data, and events across your web and mobile applications. It helps product and marketing teams understand how users interact with their product — from first touch to conversion and retention.

Connecting Amplitude to Coupler.io lets you pull your analytics data into spreadsheets, BI tools, or AI assistants without manual exports. You can combine Amplitude data with other sources, automate refreshes, and build dashboards on top of live data.

**Why connect Amplitude to Coupler.io?**

* Export events, active users, cohorts, and session data to Google Sheets, BigQuery, Looker Studio, Excel, or AI destinations like ChatGPT and Gemini
* Combine Amplitude data with CRM or ad spend data using Join or Append transformations
* Automate reporting so your dashboards always reflect the latest product metrics
* Avoid Amplitude's export limits by pulling data incrementally with a custom start date

## Prerequisites

Before connecting, make sure you have:

* An Amplitude account with access to the project you want to pull data from
* Your Amplitude **API key** and **Secret key** (found in your project settings under **Settings → Projects → \[Your Project] → General**)
* Admin or member-level access to the project (read access is sufficient)

## Quick start

{% hint style="success" %}
Start with the **Events** or **Active users** entity — these give you the richest data for product and marketing analysis right away.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** Log into your Coupler.io account, go to **Data flows**, and click **Add data flow**. Search for **Amplitude** and select it as your source.
{% endstep %}

{% step %}
**Enter your Amplitude API credentials.** In the connection settings, paste your Amplitude **API key** and **Secret key**. Both are available in your Amplitude project under **Settings → Projects → \[Project name] → General**.
{% endstep %}

{% step %}
**Select an entity.** Choose the data type you want to pull — Events, Active users, Cohorts, Average session lengths, Events list, or Annotations. You can add more entities to the same data flow later.
{% endstep %}

{% step %}
**Configure basic settings.** Set a **start date** using the date picker to define how far back data should be exported. For the Events entity, also set a **request time range** (in hours) to avoid timeout errors on large datasets — shorter intervals are safer for high-volume projects.
{% endstep %}

{% step %}
**Choose your destination.** Select where you want the data to land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination such as Claude, ChatGPT, Cursor, Gemini, Perplexity, or OpenClaw.
{% endstep %}

{% step %}
**Run your data flow.** Click **Run** to execute a manual sync. Once it completes successfully, your Amplitude data will appear in the destination you selected.
{% endstep %}
{% endstepper %}

## Available entities

| Entity                  | What it contains                                        |
| ----------------------- | ------------------------------------------------------- |
| Events                  | Raw event data with user, session, and property details |
| Active users            | Daily/weekly/monthly active user counts                 |
| Average session lengths | Session duration metrics over time                      |
| Cohorts                 | User cohorts defined in Amplitude                       |
| Events list             | Catalog of all event types tracked in your project      |
| Annotations             | Chart annotations added to your Amplitude project       |

## Amplitude data overview

Amplitude exposes six entities through Coupler.io, ranging from raw event-level data to aggregated behavioral metrics. The right entity depends on whether you need granular user actions or summary-level analytics.

## Entities at a glance

| Entity                  | Granularity         | Best for                              |
| ----------------------- | ------------------- | ------------------------------------- |
| Events                  | Row per event       | Funnel analysis, user journey mapping |
| Active users            | Row per time period | DAU/WAU/MAU tracking                  |
| Average session lengths | Row per time period | Engagement benchmarking               |
| Cohorts                 | Row per cohort      | Retention and segmentation analysis   |
| Events list             | Row per event type  | Auditing tracked events               |
| Annotations             | Row per annotation  | Contextualizing metric changes        |

## Events

#### Event fields

| Field              | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `event_type`       | Name of the event (e.g., `button_click`, `purchase`) |
| `event_time`       | Timestamp of when the event occurred                 |
| `user_id`          | Identifier for the user who triggered the event      |
| `device_id`        | Device identifier (used when user\_id is absent)     |
| `session_id`       | Groups events into a single session                  |
| `platform`         | Platform (iOS, Android, Web)                         |
| `country`          | Country of the user                                  |
| `region`           | Region/state of the user                             |
| `os_name`          | Operating system                                     |
| `device_type`      | Device category                                      |
| `event_properties` | Key-value pairs specific to the event                |
| `user_properties`  | Key-value pairs describing the user at event time    |

## Active users

#### Active user fields

| Field     | Description                                         |
| --------- | --------------------------------------------------- |
| `date`    | Date of the measurement                             |
| `value`   | Count of active users on that date                  |
| `country` | Country of users (when group-by-country is enabled) |

## Average session lengths

#### Session length fields

| Field   | Description                              |
| ------- | ---------------------------------------- |
| `date`  | Date of the measurement                  |
| `value` | Average session duration in milliseconds |

## Cohorts

#### Cohort fields

| Field           | Description                              |
| --------------- | ---------------------------------------- |
| `id`            | Unique cohort identifier                 |
| `name`          | Name of the cohort                       |
| `size`          | Number of users in the cohort            |
| `description`   | Cohort description                       |
| `last_computed` | Timestamp of the last cohort computation |
| `owners`        | List of owners                           |
| `published`     | Whether the cohort is published          |

## Events list

#### Event type fields

| Field        | Description                                      |
| ------------ | ------------------------------------------------ |
| `event_type` | Name of the tracked event                        |
| `totals`     | Total number of times this event has occurred    |
| `visible`    | Whether the event is visible in the Amplitude UI |

## Annotations

#### Annotation fields

| Field     | Description                    |
| --------- | ------------------------------ |
| `id`      | Annotation identifier          |
| `date`    | Date the annotation applies to |
| `label`   | Short annotation label         |
| `details` | Full annotation text           |

## Common metric combinations

* **Events + Active users** — Join these in Coupler.io to normalize event volume by active user count and calculate per-user engagement rates
* **Events + Cohorts** — Use Cohorts to filter or segment Events data when building retention dashboards
* **Active users over time + Annotations** — Append Annotations alongside Active users data to explain spikes and drops in your charts
* **Average session lengths + Active users** — Combine with an Aggregate transformation to surface engagement quality alongside reach metrics

## Use cases by role

{% tabs %}
{% tab title="Product managers" %}

* Pull **Events** data into BigQuery or Google Sheets to build custom funnel reports outside Amplitude's UI
* Track **DAU/WAU/MAU** trends in a Looker Studio dashboard that refreshes automatically
* Use **Cohorts** to compare behavior between user segments in a spreadsheet pivot table
* Feed event data into ChatGPT or Gemini to ask natural language questions about user behavior patterns
  {% endtab %}

{% tab title="Marketers" %}

* Combine **Active users** (grouped by country) with ad spend data from your ad platform using a Join transformation to calculate cost per active user by region
* Export **Events** to track campaign-triggered actions (signups, purchases) alongside attribution data
* Use **Annotations** to document marketing campaigns directly in your analytics timeline
  {% endtab %}

{% tab title="Data analysts" %}

* Export raw **Events** to BigQuery for custom SQL analysis not available in Amplitude's built-in charts
* Use **Events list** to audit which events are actively tracked and clean up your taxonomy
* Append **Active users** from multiple Amplitude projects into a single dataset using the Append transformation for cross-product comparisons
* Schedule recurring exports to keep a historical data warehouse in sync with Amplitude
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* The **Events** entity uses Amplitude's Export API, which returns compressed data in batches. Large date ranges on high-volume projects can trigger timeouts — use the **request time range** parameter to break requests into smaller intervals.
* **Active users grouped by country** makes a separate API call per country. If your project tracks many countries, this can be slow or cause connection errors — disable it if needed.
* **Cohort** data reflects the state of the cohort at the time of the sync, not historical membership snapshots.
* The `event_properties` and `user_properties` fields contain nested JSON. Some destinations (like BigQuery) will store these as JSON columns; spreadsheet destinations may flatten or truncate them.
* Amplitude's Export API only supports data from after your project's creation date — you cannot pull data that predates the project.

## Amplitude common issues

### Connection issues

<details>

<summary>Invalid API key or Secret key error</summary>

Double-check that you've entered both the **API key** and the **Secret key** correctly — these are two separate values in Amplitude's project settings. Go to **Settings → Projects → \[Your project] → General** and copy each key carefully. Make sure there are no extra spaces before or after the keys when pasting.

</details>

<details>

<summary>Connected to the wrong Amplitude project</summary>

Each Amplitude project has its own API key and Secret key. If you're seeing unexpected data (or no data), verify that the credentials you used belong to the correct project. Check under **Settings → Projects** in Amplitude to confirm which project each key belongs to.

</details>

### Missing data

<details>

<summary>No data returned for the Events entity</summary>

The most common cause is a start date that's too recent or a request time range that's too short to capture events. Try adjusting your start date further back using the date picker. Also check that the Amplitude project actually has event data recorded — verify in the Amplitude UI first.

</details>

<details>

<summary>Active users data is missing or incomplete when grouped by country</summary>

Grouping active users by country triggers a separate API call for each country. This can result in partial data or connection failures for projects with many countries. Try disabling **Group by country** in the advanced settings to pull total active user counts without the country breakdown.

</details>

<details>

<summary>Cohort size shows 0 or cohort is missing</summary>

Cohorts in Amplitude must be computed before they can be exported. If a cohort was recently created or hasn't been recalculated, it may appear empty. In Amplitude, trigger a manual recompute of the cohort, then re-run the data flow.

</details>

### Permission errors

<details>

<summary>403 Forbidden or access denied error</summary>

The API credentials you're using may belong to a user or role without sufficient access to the Export API. Amplitude's Export API requires a project-level API key — organization-level keys won't work. Confirm that the key is a **project API key** from the correct project's settings page.

</details>

### Data discrepancies

<details>

<summary>Event counts in Coupler.io don't match what I see in Amplitude charts</summary>

Amplitude charts apply filters, segmentation, and sometimes sampling that aren't reflected in raw Export API data. The Events entity in Coupler.io returns raw, unfiltered event records. Differences are expected — use the Events entity as your source of truth for raw counts, and apply filtering in your destination.

</details>

<details>

<summary>event_properties or user_properties look truncated or malformed</summary>

These fields contain nested JSON objects. Spreadsheet destinations like Google Sheets may truncate or display them as plain text strings. If you need to work with nested properties, export to BigQuery where JSON columns are fully supported, or use Coupler.io's transformation layer to extract specific property values.

</details>

### Rate limits

<details>

<summary>Timeout errors when pulling Events data</summary>

Amplitude's Export API can time out when the requested time range is too large, especially for high-volume projects. Lower the **request time range** parameter (measured in hours) to break the export into smaller chunks. A value of 1–6 hours is recommended for projects with millions of daily events. See [Amplitude's Export API documentation](https://www.docs.developers.amplitude.com/analytics/apis/export-api/#considerations) for more detail.

</details>

## Amplitude FAQ

<details>

<summary>Where do I find my Amplitude API key and Secret key?</summary>

In Amplitude, go to **Settings → Projects**, select your project, and open the **General** tab. You'll see both the **API key** and **Secret key** listed there. Note that these are project-level credentials — each project has its own unique pair.

</details>

<details>

<summary>Can I pull data from multiple Amplitude projects into one destination?</summary>

Yes. Add multiple sources to the same data flow — one per Amplitude project, each with its own API credentials. Use the **Append** transformation to combine the data into a single table. This is useful if you have separate Amplitude projects for iOS and Android apps and want a unified view.

</details>

<details>

<summary>Why does the Events entity take so long to load?</summary>

The Events entity uses Amplitude's Export API, which can be slow for large date ranges or high-volume projects. Reduce the **request time range** parameter to a smaller number of hours to break the request into smaller batches. Start with 6 hours and go lower if you still experience timeouts.

</details>

<details>

<summary>Can I use Amplitude data with AI tools?</summary>

Yes. Coupler.io supports AI destinations including **ChatGPT, Claude, Gemini, Cursor, Perplexity, and OpenClaw**. You can pipe your Amplitude events or active user data directly into these tools and ask natural language questions about user behavior, drop-off points, or engagement trends.

</details>

<details>

<summary>Why are my event_properties showing as a long string instead of separate columns?</summary>

Amplitude stores event and user properties as nested JSON objects. Spreadsheet destinations like Google Sheets display these as raw JSON strings. If you need individual property values as separate columns, consider exporting to BigQuery where JSON is natively supported, or use Coupler.io's transformation features to extract specific fields.

</details>

<details>

<summary>What's the difference between Events and Events list?</summary>

**Events** returns raw event records — every individual action a user took, with timestamps and properties. **Events list** returns the catalog of event *types* defined in your project (e.g., `page_viewed`, `purchase_completed`) along with total occurrence counts. Use Events list to audit your tracking taxonomy; use Events for behavioral analysis.

</details>

<details>

<summary>Can I join Amplitude data with data from another source?</summary>

Yes. Coupler.io's **Join** transformation lets you combine Amplitude data with data from other sources — for example, joining Amplitude Events with Salesforce or HubSpot CRM data on a shared user ID, or joining Active users with ad spend data from Google Ads to calculate cost per active user.

</details>

<details>

<summary>Does Coupler.io support historical backfills for Amplitude data?</summary>

Yes — set your start date using the date picker to any date after your Amplitude project was created. Keep in mind that very long historical ranges can trigger timeout errors for the Events entity. Pull history in chunks by adjusting the request time range parameter.

</details>

{% hint style="info" %}
For details on what fields are available per entity, see [Data Overview](#amplitude-data-overview). If you're hitting timeout or connection errors, check [Common Issues](#amplitude-common-issues) for specific fixes. For tips on structuring your data flow efficiently, see [Best Practices](https://docs.coupler.io/sources/category/marketing/amplitude/best-practices.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/marketing/amplitude.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
