
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-DDformat. 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).
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 acharts_metadatastream. - 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.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.
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
- 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.
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.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:Events
Events
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.Chart Streams
Chart Streams
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: Example data:
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.
Charts Metadata
Charts Metadata
A single stream containing metadata about all your configured charts. This stream provides context about what each chart measures.Stream Naming:
charts_metadataThis 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_metadatastream contains information about all configured charts - Plus events stream: The
eventsstream 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_nameanddimension_valuefields can represent any dimension your chart uses (country, device, event name, etc.) - Segment variations: The
segmentfield 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
valuefield - 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_timeas a bookmark to fetch only new events on each extraction. The first sync starts from the configuredstart_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 yourEvent Export Window (Days) configuration:
The tap will log a clear error message with the current window size and instructions to adjust it.
Best Practices
- Select relevant charts: Only configure Chart IDs for the metrics you need to reduce API calls and data volume
- Use metadata stream: Join chart data with the
charts_metadatastream to add context to your analysis - 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.
- 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. - Schedule appropriately: Amplitude analytics typically update daily, so daily sync frequency is usually sufficient. Remember the ~2 hour export delay for raw events.
- 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.