Skip to main content
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 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: xyz789Tips:
  • 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, 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 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, 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.
FieldTypeDescription
chart_idStringThe Amplitude chart ID.
dimension_nameStringThe name of the dimension being measured (e.g., “Country”, “Device Type”, “Event Name”).
dimension_valueStringThe value for this dimension (e.g., “United States”, “iOS”, “Page View”).
segmentStringThe segment or cohort this data represents (e.g., “All Users”, “New Users”, date labels for time series).
valueNumberThe 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_iddimension_namedimension_valuesegmentvalue
abc123CountryUnited States2024-01-1515420
abc123CountryUnited States2024-01-1616234
abc123CountryCanada2024-01-153421
abc123CountryCanada2024-01-163567
A single stream containing metadata about all your configured charts. This stream provides context about what each chart measures.
FieldTypeDescription
chart_idStringThe Amplitude chart ID.
titleStringThe title/name of the chart as shown in Amplitude.
metricStringThe metric being measured (e.g., “Uniques”, “Event Totals”, “Average”).
eventStringThe event being tracked (if applicable).
dimensionStringThe dimension the chart is grouped by.
filtersStringAny 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.
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

IssuePossible CauseSolution
Authentication errorsIncorrect API key or secret keyVerify credentials in Amplitude settings - ensure you’re using the correct project’s secret key
No data extractedInvalid Chart IDsVerify Chart IDs by checking URLs in Amplitude - ensure charts exist and you have access
Empty streamsChart has no dataCheck that the chart contains data in Amplitude before syncing
Unexpected data structureChart configuration changedRe-extract the data - the structure reflects the current chart configuration in Amplitude
Missing dimensionsChart not showing expected breakdownsVerify 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