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

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Amplitude data source in Adriel.

## Introduction

Amplitude is a product analytics platform built around an event-based data model. Every user interaction is logged as an event with properties, and downstream analyses include event segmentation (totals and unique users per event), funnel conversion analysis, user counts (new and active), and cohort segmentation. Data is scoped to an Amplitude Project — a single workspace inside the Amplitude organization.

The connector reads from the Amplitude Dashboard REST API v2 and exposes events, funnels, and user metrics. The list of available metrics is built dynamically from the project's event catalog, so any event tracked into Amplitude becomes a queryable metric. One data source is created per Amplitude Project; each project has its own API Key and Secret Key.

As an analytics connector, session, event, and breakdown data are standardized so widgets can aggregate alongside ad-platform sources without additional configuration. To connect this data source, see [How to connect Amplitude to Adriel](/data-sources/a-f/amplitude/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers the Amplitude Project and its event catalog. The catalog is fetched from Amplitude on first use and memoized for **5 minutes** per `(data source, project)` pair, so events newly defined in Amplitude can take up to 5 minutes to appear in the field picker. Two fixed user metrics — New users and Active users — are always available regardless of the event catalog.

### Reports data

Reports data is fetched **on demand**. Each dashboard load issues a live request to the relevant Amplitude API endpoint (event segmentation, funnels, or users) for the selected metrics, breakdowns, and date range. Numbers reflect Amplitude's current ingestion and processing state at request time — there is no nightly snapshot or fixed refresh window.

## Architecture levels

Organization → Project → Event → User / Cohort

An Amplitude Project is the reporting boundary. Events are tracked into the project, and users (and the cohorts derived from them) are the subjects those events describe.

## Date range limits

| Scope            | Maximum range       |
| ---------------- | ------------------- |
| Any single query | 6 months (186 days) |

Queries spanning more than 6 months are rejected at validation ("We don't support more than 6 months of data"). Split longer analyses into multiple queries, each within the 6-month window.

## Metrics

<Note>
  **How to read the columns**

  Code style like `active_users` is the literal Amplitude field or metric prefix. For per-event metrics, `{event}` stands for the event display name appended at runtime, and `{cohort}` is either `new` or `active`. *Italic text* describes how a value is produced when it doesn't map cleanly to a single Amplitude field or when it's computed by Adriel.

  **Data type vocabulary**: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.
</Note>

<Note>
  **Metrics are generated per event, and per cohort**

  Available metrics are built at runtime from the Amplitude event catalog. For each event, the connector emits event, funnel, and frequency metrics both for the full audience and for two cohorts — new users (a rolling 30-day segment defined by Adriel) and active users — so the same event can be compared across cohorts in one widget.
</Note>

### Users & sessions

| Metric       | Description                                                                                | Data type | API Key        |
| ------------ | ------------------------------------------------------------------------------------------ | --------- | -------------- |
| Active users | Distinct users active in the period (DAU, WAU, or MAU depending on the selected interval). | Number    | `active_users` |
| New users    | Users first seen in the period (rolling 30-day new-user definition).                       | Number    | `new_users`    |

### Engagement

| Metric                              | Description                                                          | Data type | API Key                               |
| ----------------------------------- | -------------------------------------------------------------------- | --------- | ------------------------------------- |
| Event totals - {event}              | Total number of times the event was triggered in the period.         | Number    | `event totals - {event}`              |
| Event uniques - {event}             | Distinct users who triggered the event.                              | Number    | `event uniques - {event}`             |
| Event uniques (new users) - {event} | Distinct new users (rolling 30-day segment) who triggered the event. | Number    | `event uniques (new users) - {event}` |

### Events & conversions

Funnel and frequency metrics are generated per event, for both the new-user and active-user cohorts.

| Metric                                              | Description                                 | Data type  | API Key                                           |
| --------------------------------------------------- | ------------------------------------------- | ---------- | ------------------------------------------------- |
| New / active user transitions - {event}             | Number of funnel transitions into the step. | Number     | `{cohort} user transitions - {event}`             |
| New / active user transitions (%) - {event}         | Funnel conversion percentage at the step.   | Percentage | `{cohort} user transitions (%) - {event}`         |
| New / active user average transition time - {event} | Mean time to complete the step.             | Duration   | `{cohort} user average transition time - {event}` |
| New / active user median transition time - {event}  | Median time to complete the step.           | Duration   | `{cohort} user median transition time - {event}`  |
| Frequency (1 time) - {event}                        | Users who completed the step exactly once.  | Number     | `frequency ({cohort} user / 1 time) - {event}`    |
| Frequency (2 times) - {event}                       | Users who completed the step exactly twice. | Number     | `frequency ({cohort} user / 2 times) - {event}`   |

### Revenue & monetization

| Metric                         | Description                                                                                                                             | Data type | API Key                                                                                                   |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------- |
| Revenue event totals / uniques | Monetization is surfaced through the standard event metrics applied to a revenue-tagged event (for example, `event totals - purchase`). | Number    | *Reflects the revenue event configured in Amplitude; reuses the event totals and event uniques prefixes.* |

## Breakdowns

<Note>
  **How to read the columns**

  Code style like `country` is the literal Amplitude group-by value. *Italic text* describes a value whose key is configured per data source or produced by Adriel.
</Note>

### Geography

| Breakdown | Description                  | API Key   |
| --------- | ---------------------------- | --------- |
| Country   | Country of the user.         | `country` |
| Region    | Region or state of the user. | `region`  |

### Device & platform

| Breakdown                | Description                             | API Key       |
| ------------------------ | --------------------------------------- | ------------- |
| Platform                 | Device platform (iOS, Android, or web). | `platform`    |
| Language                 | Language setting of the user's device.  | `language`    |
| Device type              | Device family.                          | `device_type` |
| OS name                  | Operating system name.                  | `os_name`     |
| Operating system version | Operating system version.               | `os_version`  |

### Customer

| Breakdown | Description                            | API Key  |
| --------- | -------------------------------------- | -------- |
| Paying    | Whether the user is a paying customer. | `paying` |

### Acquisition

| Breakdown    | Description                 | API Key        |
| ------------ | --------------------------- | -------------- |
| UTM source   | UTM source user property.   | `utm_source`   |
| UTM medium   | UTM medium user property.   | `utm_medium`   |
| UTM campaign | UTM campaign user property. | `utm_campaign` |
| Referrer     | Referring URL or domain.    | `referrer`     |

### Event

| Breakdown      | Description                                      | API Key                                                        |
| -------------- | ------------------------------------------------ | -------------------------------------------------------------- |
| Event name     | Name of the tracked event.                       | `event_type`                                                   |
| Event property | Group by an event property defined in Amplitude. | *`event_property` — any property name configured in Amplitude* |

### User property

| Breakdown     | Description                                                                                   | API Key                                            |
| ------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| User property | Group by a user property configured on the data source (plan tier, role, segment, and so on). | *`gp:{propertyName}` — configured per data source* |

### Time

| Breakdown | Description                 | API Key |
| --------- | --------------------------- | ------- |
| Daily     | Day-level date breakdown.   | `i=1`   |
| Weekly    | Week-level date breakdown.  | `i=7`   |
| Monthly   | Month-level date breakdown. | `i=30`  |

## Limitations

Based on the current connector, Amplitude has:

* **A 6-month (186-day) cap on the date range for a single query** — longer ranges are rejected at validation and must be split into multiple queries ([Amplitude Dashboard REST API](https://amplitude.com/docs/apis/analytics/dashboard-rest)).
* **Breakdown caps that vary by query mode** — event segmentation accepts up to 2 non-date breakdowns; funnel metrics accept at most 1 breakdown and only `day` date granularity (weekly or monthly raises `INVALID_BREAKDOWN_FOR_CHART`); user metrics (New users, Active users) accept at most 1 breakdown ([Amplitude Dashboard REST API](https://amplitude.com/docs/apis/analytics/dashboard-rest)).
* **Unpopulated user counts on non-date breakdowns** — New users and Active users return values for date breakdowns and the ungrouped total; breaking them down by a non-date breakdown (for example, country) returns the grouping labels without user counts.
* **No City breakdown** — grouping by city is intentionally not offered because Amplitude truncates high-cardinality city results.
* **Truncated high-cardinality results** — when Amplitude prunes a large result, a `TOO_MUCH_DATA_REQUESTED_INCOMPLETE` warning is surfaced and the widget shows the partial data with an explicit caveat.
* **A 5-minute lag on newly defined events** — the event catalog is memoized for 5 minutes, so new events appear in the field picker only after the cache refreshes.
* **One data source per Amplitude Project** — each project has its own API Key and Secret Key; one project's credentials cannot read another project's events.
* **Rate limits from Amplitude** — when Amplitude rate-limits a request (HTTP 429), the connector surfaces the API's response so the query can be retried.

## API references

* [Amplitude Dashboard REST API (v2)](https://amplitude.com/docs/apis/analytics/dashboard-rest)
* [Event Segmentation API](https://amplitude.com/docs/apis/analytics/event-segmentation)
* [Funnel Analysis API](https://amplitude.com/docs/apis/analytics/funnels)
* [Active and New User Counts API](https://amplitude.com/docs/apis/analytics/active-and-new-user-counts)

## See also

* [How to connect Amplitude](/data-sources/a-f/amplitude/how-to-connect) (paired how-to)
* [Google Analytics 4 data reference](/data-sources/g-n/google-analytics-4/data-reference) — for the web and app analytics counterpart
* [Piano Analytics data reference](/data-sources/o-z/piano-analytics/data-reference) — for the alternative analytics connector