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 for this connection. Both credentials must be project-scoped. The following configurations are available:
  • API Key: Your project-specific Amplitude API key for authentication. You can find it in your Amplitude workspace under Settings > Projects > [Your Project] > General > API Key. (Do not use the organization-level API key name, as it will return a 403 error).
  • Secret Key: Your project-specific secret key. Find it under Settings > Projects > [Your Project] > General > Secret key.
  • Chart IDs (optional): The IDs of the Amplitude charts you want to extract data from. You can extract data from multiple charts by providing multiple Chart IDs. Each chart creates a separate stream.
  • Start Date: The start date for raw event export, in YYYY-MM-DD format. When empty, the events stream starts 30 days ago.
  • Event Export Window (Days): Number of days per API request when exporting raw events. Lower values reduce memory usage for high-volume projects. Defaults to 365 (the API maximum).
Once you’re done, click Next.

2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. The Amplitude connector provides two types of streams:
  • Chart streams: Dynamically created based on your configured Chart IDs. Each chart creates a separate stream named chart_{chart_id}, plus a charts_metadata stream.
  • Events stream: Raw event data exported from Amplitude, containing every tracked user event with full detail.
You can use chart streams, the events stream, or both. Chart IDs are only required if you want to extract chart data. If no Chart IDs are provided, only the events stream is discovered.
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 chart streams: FULL_TABLE sync is recommended since chart data represents aggregated metrics that should reflect the current state.
    • For the events stream: INCREMENTAL sync is recommended to efficiently fetch only new events since the last extraction.
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
Optionally, you can define some additional settings:
  • Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
  • Determine when to execute an Additional Full Sync. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
The Amplitude Export API has a data delay of approximately 2 hours. Events will only be available for extraction after Amplitude finishes processing them, and the stream inherently ends on the last complete hour past that delay.
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

Available streams

The table below lists every stream, its slug (the exact identifier to pass when creating the source via API) and a short description. Streams marked dynamic are only discovered when the corresponding setting is populated.

Fields by stream

Below you’ll find all available data streams from Amplitude and their corresponding fields:
Raw event data exported from Amplitude via the Export API. Each record represents a single tracked event with full user, device, and session context.This stream supports incremental sync using the event_time field as the bookmark, so subsequent extractions only fetch new events.
JSON String Fields: Fields like event_properties, user_properties, and group_properties are stored as JSON strings because their structure varies per event. You can parse them in your transformations to extract specific properties.
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.
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:
A single stream containing metadata about all your configured charts. This stream provides context about what each chart measures.Stream Naming: charts_metadata
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, a metadata stream, and a raw events stream.
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. The events stream is independent and contains raw event-level data.

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
  • Plus events stream: The events stream is always available for selection regardless of chart configuration. If no charts are configured, it is the only stream discovered.
  • 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
  • JSON string fields: Dynamic fields (event_properties, user_properties, group_properties, global_user_properties, groups, data, plan) in the events stream are serialized as JSON strings to accommodate their dynamic schemas per event.

Authentication

  • HTTP Basic Auth: Both the Dashboard API and Export API use your API key as the username and secret key as the password.
  • Project-specific: Both credentials must be generated at the project level (Settings > Projects > [project] > General). The key name visible in the Organization settings page will not work and will result in a 403 error.

Sync Strategy

  • Charts: Full table sync: Chart data represents aggregated metrics and should be refreshed completely on each sync
  • Events: Incremental sync: The events stream uses event_time as a bookmark to fetch only new events on each extraction. The first sync starts from the configured start_date (or defaults to 30 days ago).

Handling Large Event Volumes

The Amplitude Export API has limits on response size and request duration. If you encounter errors, check your Event Export Window (Days) configuration: The tap will log a clear error message with the current window size and instructions to adjust it.
For very large-scale extraction, Amplitude recommends using their native Snowflake, BigQuery, or S3 integrations instead of the API. Consider this if your daily event volume consistently exceeds millions of events.

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. Set an appropriate start date: For the events stream, choose a start date that balances historical coverage with initial sync time. If empty, defaults to 30 days ago.
  4. Tune the export window: If you have high event volume, start with a smaller Event Export Window (Days) (e.g., 7) and increase if needed.
  5. Schedule appropriately: Amplitude analytics typically update daily, so daily sync frequency is usually sufficient. Remember the ~2 hour export delay for raw events.
  6. Parse JSON fields: Use SQL transformations to extract specific properties from the JSON string fields in the events stream

Troubleshooting

Skills for agents

Download Amplitude skills file

Amplitude connector documentation as plain markdown, for use in AI agent contexts.