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. 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 (optional): The IDs of the Amplitude charts you want to extract data from.
Start Date: The start date for raw event export, in YYYY-MM-DD format. If the events stream is selected and this is not configured, it will default to 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).

How to get API Key and Secret Key

API Key:

Log in to your Amplitude workspace
Go to Settings (gear icon in the top-right)
Navigate to Organization settings > API Keys
Copy your API key from this page

Secret Key:

In Amplitude, go to Settings
Navigate to Projects in the left sidebar
Select your project
Go to the General tab
Scroll down to find the Secret key field
Copy the secret key

Keep your API key and secret key secure. These credentials provide access to your Amplitude data.

How to find Chart IDs

To find the ID of an Amplitude chart:

Open your Amplitude workspace and navigate to the chart you want to sync
Look at the URL in your browser’s address bar
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 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.

Choose which streams you want to sync 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.

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 provides chart data streams, a charts metadata stream, and a raw events stream.

Chart Streams (chart_{chart_id})

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

Charts Metadata (charts_metadata)

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.

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.

Field	Type	Description
`uuid`	String	Unique identifier for the event.
`event_type`	String	The name of the event (e.g., “Page Viewed”, “Button Clicked”).
`event_time`	DateTime	The time the event occurred (UTC). Used as the replication key for incremental sync.
`server_received_time`	DateTime	When Amplitude’s servers received the event.
`processed_time`	DateTime	When Amplitude finished processing the event.
`client_upload_time`	DateTime	When the client uploaded the event.
`server_upload_time`	DateTime	When the server uploaded the event.
`client_event_time`	DateTime	The event time as reported by the client.
`user_id`	String	The user ID associated with the event.
`device_id`	String	The device ID associated with the event.
`amplitude_id`	Integer	Amplitude’s internal user identifier.
`session_id`	Integer	The session ID for the event.
`event_id`	Integer	A counter for events within a session.
`app`	Integer	The Amplitude app/project ID.
`platform`	String	The platform (e.g., “Web”, “iOS”, “Android”).
`os_name`	String	The operating system or browser name.
`os_version`	String	The operating system or browser version.
`device_type`	String	The type of device (e.g., “Mac”, “Windows”, “iPhone”).
`device_family`	String	The device family (e.g., “Mac OS X”, “Windows”).
`device_carrier`	String	The mobile carrier.
`library`	String	The Amplitude SDK library and version.
`version_name`	String	The app version name.
`start_version`	String	The app version when the user was first seen.
`language`	String	The user’s language setting.
`ip_address`	String	The user’s IP address.
`city`	String	The user’s city.
`country`	String	The user’s country.
`region`	String	The user’s region/state.
`dma`	String	The designated market area.
`location_lat`	Number	Latitude of the user’s location.
`location_lng`	Number	Longitude of the user’s location.
`paying`	Boolean	Whether the user is a paying user.
`sample_rate`	Number	The sample rate applied to the event.
`amplitude_attribution_ids`	String	Amplitude attribution IDs.
`amplitude_event_type`	String	Amplitude’s internal event type classification.
`insert_id`	String	A unique insert identifier for deduplication.
`insert_key`	String	A unique insert key.
`schema`	Integer	The schema version of the event.
`device_brand`	String	The device brand.
`device_manufacturer`	String	The device manufacturer.
`device_model`	String	The device model.
`adid`	String	The Android advertising ID.
`idfa`	String	The iOS identifier for advertisers.
`source_id`	String	The source ID of the event.
`partner_id`	String	The partner ID for attribution.
`data_type`	String	The type of data record (e.g., “event”).
`is_attribution_event`	Boolean	Whether this is an attribution event.
`user_creation_time`	DateTime	When the user was first seen.
`plan`	String (JSON)	Tracking plan information as a JSON string.
`global_user_properties`	String (JSON)	Global user properties as a JSON string.
`event_properties`	String (JSON)	Event-specific properties as a JSON string.
`user_properties`	String (JSON)	User properties at the time of the event as a JSON string.
`group_properties`	String (JSON)	Group properties as a JSON string.
`groups`	String (JSON)	Group membership as a JSON string.
`data`	String (JSON)	Additional event metadata as a JSON string.

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.

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
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: 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

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:

Error	Cause	Solution
400 - Response exceeds 4 GB	Too many events in the time window	Reduce `event_export_window_days` to a smaller value (e.g., 7 or 1)
504 - Request timed out	Data volume too large for the time window	Reduce `event_export_window_days` to a smaller value

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

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_metadata stream 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
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

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
Events export fails with 400	Response exceeds 4 GB	Reduce `event_export_window_days` in your configuration
Events export fails with 504	Request timed out	Reduce `event_export_window_days` in your configuration
No new events exported	Within the 2-hour delay window	Wait for Amplitude to finish processing recent events
Unexpected data structure	Chart configuration changed	Re-extract the data, the structure reflects the current chart configuration in Amplitude

Skills for agents

Download Amplitude skills file

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

​Configuring Amplitude as a Source

​1. Add account access

​2. Select streams

​3. Configure data streams

​4. Configure data source

​5. Check your new source

​Streams and Fields

​Data Model

​Implementation Notes

​Dynamic Stream Discovery

​Data Structure

​Authentication

​Sync Strategy

​Handling Large Event Volumes

​Best Practices

​Troubleshooting

​Skills for agents

Download Amplitude skills file

Configuring Amplitude as a Source

1. Add account access

2. Select streams

3. Configure data streams

4. Configure data source

5. Check your new source

Streams and Fields

Data Model

Implementation Notes

Dynamic Stream Discovery

Data Structure

Authentication

Sync Strategy

Handling Large Event Volumes

Best Practices

Troubleshooting

Skills for agents