> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Amplitude as a data source
> Bring data from Amplitude analytics charts to Nekt.
Amplitude is a product analytics platform that helps teams understand user behavior, measure product engagement, and drive growth through data-driven insights. It provides powerful analytics, experimentation, and personalization capabilities.
## Configuring Amplitude as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Amplitude option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need your Amplitude API credentials and Chart IDs for this connection. Once you have them, add the account access, then click **Next**.
* **API Key**: Your Amplitude API key for authentication. You can find it in your Amplitude workspace under **Settings** > **Organization settings** > **API Keys**.
* **Secret Key**: Your project-specific secret key. Find it under **Settings** > **Projects** > **\[Your Project]** > **General** > **Secret key**.
* **Chart IDs**: The IDs of the Amplitude charts you want to extract data from.
**API Key:**
1. Log in to your Amplitude workspace
2. Go to **Settings** (gear icon in the top-right)
3. Navigate to **Organization settings** > **API Keys**
4. Copy your API key from this page
**Secret Key:**
1. In Amplitude, go to **Settings**
2. Navigate to **Projects** in the left sidebar
3. Select your project
4. Go to the **General** tab
5. Scroll down to find the **Secret key** field
6. Copy the secret key
Keep your API key and secret key secure. These credentials provide access to your Amplitude data.
To find the ID of an Amplitude chart:
1. Open your Amplitude workspace and navigate to the chart you want to sync
2. Look at the URL in your browser's address bar
3. The chart ID is the alphanumeric string in the URL after `/chart/` or in the `id` parameter
**Example URLs:**
```
https://analytics.amplitude.com/org-name/chart/abc123def
```
The chart ID is: `abc123def`
```
https://analytics.amplitude.com/org-name/workspace/project-name/analyze/chart?id=xyz789
```
The chart ID is: `xyz789`
**Tips:**
* You can extract data from multiple charts by providing multiple Chart IDs
* Each chart will create a separate stream in your data warehouse
* Make sure you have access to the charts you want to sync
Once you're done, click **Next**.
### 2. Select streams
The Amplitude connector dynamically discovers streams based on the Chart IDs you configured. **Each chart creates a separate data stream**, plus a metadata stream with information about all your charts.
**Dynamic Stream Discovery:** The connector creates one stream per chart ID. Stream names follow the pattern `chart_{chart_id}`, plus a special `charts_metadata` stream that contains information about all your charts.
For example, a chart with ID `abc123` will create a stream named `chart_abc123`.
Choose which chart streams you want to sync - you can select all charts or pick specific ones that matter most to you.
> Tip: The stream can be found more easily by typing its chart ID.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.
* **Layer**: Choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: A folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: We suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: For Amplitude charts, **FULL\_TABLE** sync is recommended since chart data represents aggregated metrics that should reflect the current state.
Amplitude chart data is typically aggregated and historical. Each extraction will fetch the complete current state of the chart data.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/get-started/core-concepts/triggers), consider how often you want data to be extracted from this source. Common configurations for Amplitude:
* **Daily**: Most common - captures daily updates to your analytics
* **Every 12 hours**: For more frequent monitoring of key metrics
* **Weekly**: For less frequently changing aggregated reports
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
The Amplitude connector creates **dynamic streams based on your configured Chart IDs**, plus a metadata stream with chart information.
Each Chart ID you configure creates a separate stream containing the chart's data in an unpivoted format. This makes it easy to analyze and aggregate metrics across different dimensions and segments.
**Stream Naming:** `chart_{chart_id}` where `{chart_id}` is your Amplitude chart identifier.
| Field | Type | Description |
| :---------------- | :----- | :-------------------------------------------------------------------------------------------------------- |
| `chart_id` | String | The Amplitude chart ID. |
| `dimension_name` | String | The name of the dimension being measured (e.g., "Country", "Device Type", "Event Name"). |
| `dimension_value` | String | The value for this dimension (e.g., "United States", "iOS", "Page View"). |
| `segment` | String | The segment or cohort this data represents (e.g., "All Users", "New Users", date labels for time series). |
| `value` | Number | The numeric metric value for this dimension/segment combination. |
**Unpivoted Data Structure:** Chart data is unpivoted, meaning each row represents a single data point for a specific dimension value and segment combination. This structure makes it flexible for analysis across different slices of your data.
**Example data:**
| chart\_id | dimension\_name | dimension\_value | segment | value |
| :-------- | :-------------- | :--------------- | :--------- | ----: |
| abc123 | Country | United States | 2024-01-15 | 15420 |
| abc123 | Country | United States | 2024-01-16 | 16234 |
| abc123 | Country | Canada | 2024-01-15 | 3421 |
| abc123 | Country | Canada | 2024-01-16 | 3567 |
A single stream containing metadata about all your configured charts. This stream provides context about what each chart measures.
| Field | Type | Description |
| :---------- | :----- | :---------------------------------------------------------------------- |
| `chart_id` | String | The Amplitude chart ID. |
| `title` | String | The title/name of the chart as shown in Amplitude. |
| `metric` | String | The metric being measured (e.g., "Uniques", "Event Totals", "Average"). |
| `event` | String | The event being tracked (if applicable). |
| `dimension` | String | The dimension the chart is grouped by. |
| `filters` | String | Any filters applied to the chart. |
This metadata stream helps you understand what each chart represents and can be joined with chart data streams using the `chart_id` field.
# Data Model
The Amplitude data model consists of unpivoted chart data streams plus a metadata stream that describes each chart.
```mermaid theme={null}
erDiagram
CHART_STREAM {
string chart_id PK
string dimension_name
string dimension_value PK
string segment PK
number value
}
CHARTS_METADATA {
string chart_id PK
string title
string metric
string event
string dimension
string filters
}
CHART_STREAM }o--|| CHARTS_METADATA : "chart_id"
```
**Multiple Chart Streams:** Each configured chart ID creates its own stream (`chart_{chart_id}`). The diagram above shows the structure that applies to all chart streams.
## Implementation Notes
### Dynamic Stream Discovery
* **One stream per chart**: Each Chart ID creates a separate stream named `chart_{chart_id}`
* **Plus metadata stream**: The `charts_metadata` stream contains information about all configured charts
* **Configure specific charts**: Only the Chart IDs you specify in the configuration are extracted
* **No automatic discovery**: Unlike some connectors, you must explicitly provide Chart IDs - the connector does not discover all available charts. When you add a new chart ID, you have to manually click on 'Add streams' to configure the table where this data will be stored.
### Data Structure
* **Unpivoted format**: Chart data is unpivoted (also called "narrow" or "long" format) with one row per dimension-segment-value combination
* **Flexible dimensions**: The `dimension_name` and `dimension_value` fields can represent any dimension your chart uses (country, device, event name, etc.)
* **Segment variations**: The `segment` field can represent time periods, user cohorts, or other groupings depending on your chart configuration
* **Numeric values**: All metric values are stored as numbers in the `value` field
### Authentication
* **HTTP Basic Auth**: Uses your API key as the username and secret key as the password
* **Project-specific**: The secret key is specific to each Amplitude project
* **Organization-level API key**: The API key is at the organization level
### Sync Strategy
* **Full table sync**: Chart data represents aggregated metrics and should be refreshed completely on each sync
* **No incremental sync**: The connector does not support incremental sync as chart data is typically historical and aggregated
* **CSV parsing**: Data is extracted from Amplitude as CSV and parsed into structured records
### Best Practices
1. **Select relevant charts**: Only configure Chart IDs for the metrics you need to reduce API calls and data volume
2. **Use metadata stream**: Join chart data with the `charts_metadata` stream to add context to your analysis
3. **Create transformations**: Parse and pivot the unpivoted data into domain-specific tables for easier querying
4. **Understand your charts**: Know what dimensions, segments, and metrics each chart contains before analyzing the data
5. **Monitor data volume**: Chart data can be large depending on the number of dimensions and time periods
6. **Schedule appropriately**: Amplitude analytics typically update daily, so daily sync frequency is usually sufficient
### Understanding Chart Data
The unpivoted structure means:
* Each unique combination of `dimension_value` and `segment` gets its own row
* A chart with 10 countries × 30 days = 300 rows minimum
* Multiple dimensions or segments multiply the row count
* The `value` field contains the actual metric (uniques, totals, averages, etc.)
### Metadata Extraction
The `charts_metadata` stream provides:
* **Title**: Human-readable chart name
* **Metric**: What's being measured (Uniques, Totals, etc.)
* **Event**: Which event is tracked
* **Dimension**: What dimension the data is grouped by
* **Filters**: Any filters applied to the chart
### Troubleshooting
| Issue | Possible Cause | Solution |
| :------------------------ | :------------------------------------ | :---------------------------------------------------------------------------------------------- |
| Authentication errors | Incorrect API key or secret key | Verify credentials in Amplitude settings - ensure you're using the correct project's secret key |
| No data extracted | Invalid Chart IDs | Verify Chart IDs by checking URLs in Amplitude - ensure charts exist and you have access |
| Empty streams | Chart has no data | Check that the chart contains data in Amplitude before syncing |
| Unexpected data structure | Chart configuration changed | Re-extract the data - the structure reflects the current chart configuration in Amplitude |
| Missing dimensions | Chart not showing expected breakdowns | Verify chart configuration in Amplitude - ensure all desired dimensions are included |
### Chart ID Best Practices
* **Document your charts**: Keep a mapping of Chart IDs to their business purpose
* **Group related charts**: Configure multiple related charts in the same source for easier analysis
* **Version control**: If chart definitions change, consider creating new Chart IDs to maintain historical consistency
* **Access control**: Ensure your API credentials have access to all configured charts
## Skills for agents
Amplitude connector documentation as plain markdown, for use in AI agent contexts.