Amplitude

Retrieve full chart objects by their IDs using the chart service directly

WHEN TO USE:

• You want to retrieve a full chart definition.
• Useful if you want to base an ad hoc query dataset analysis on an exsiting chart.

INSTRUCTIONS:

• Use the search tool to find the IDs of charts you want to retrieve, then call this tool with the IDs.

Get context information about the current user, org, and projects.

Get specific dashboards and all their charts

WHEN TO USE:

• You want to retrieve full dashboard definitions including chart IDs that you can query and analyze individually.

INSTRUCTIONS:

• Use the search tool to find the IDs of dashboards you want to retrieve, then call this tool with the IDs.
• Very commonly you will want to query the charts after retrieving a dashboard.

Retrieve event properties for a specific event type from a project. This tool provides a concise way to get all properties associated with a particular event.

WHEN TO USE:

• You want to get all properties associated with a particular event with the EXACT event type.

INSTRUCTIONS:

• Search for the exact event type you want to get properties for using the search tool or the get_events tool.
• Use this tool to get all event properties associated with a particular event.

Retrieve specific experiments by their IDs.

WHEN TO USE:

• You want to retrieve addition information for experiments like state, decisions, etc.

INSTRUCTIONS:

• Use the search tool to find the IDs of experiments you want to retrieve, then call this tool with the IDs.

Retrieve specific feature flags by their IDs.

WHEN TO USE:

• You want to retrieve full flag definitions including variants, metadata, and configuration details.

INSTRUCTIONS:

• Use the search tool to find the IDs of flags you want to retrieve, then call this tool with the IDs.

Retrieve objects from Amplitude URLs

WHEN TO USE:

• CRITICAL: Only use this tool if the user shares a link to an amplitude URL which starts with https://app.amplitude.com!
• You have an Amplitude URL and want to get the full object definition
• User shares a link to a dashboard, chart, notebook, experiment, etc.

INSTRUCTIONS:

• Provide the full Amplitude URL (e.g., https://app.amplitude.com/analytics/myorg/chart/456)
• The tool will parse the URL, validate the organization, and return the full object
• Works with charts, dashboards, notebooks, experiments, flags, cohorts, and metrics

Get detailed information about specific metrics by their IDs.

WHEN TO USE:

• You want to retrieve full metric definitions after finding them via search.
• You need detailed metric information including params, key properties, and metadata.

INSTRUCTIONS:

• Use the search tool to find the IDs of metrics you want to retrieve, then call this tool with the IDs.
• This returns full metric objects with all details, unlike the search tool which returns summary information.
• If you already have the metric ID, you can not use this tool and instead query the metric directly using query_metric if that is what the user wants.

Get specific notebooks and all their charts

WHEN TO USE:

• You want to retrieve full notebook definitions including chart IDs that you can query and analyze individually.

INSTRUCTIONS:

• Use the search tool to find the IDs of notebooks you want to retrieve, then call this tool with the IDs.
• Very commonly you will want to query the charts after retrieving a notebook.
• The returned notebook rows have markdown content and use the same schema as create_notebook, so you can directly copy and modify them to create new notebooks.

Search session replays for a project using segment filters.

WHEN TO USE:

• You want to find session replays that match user segments or conditions (e.g., variant membership, cohorts, user properties).

INSTRUCTIONS:

• Provide the projectId and one or more segments with conditions.
• Searches the last 30 days with a limit of 10 replays by default.
• Optionally include eventCountFilters, groupBys, and limit.

IMPORTANT: ALWAYS provide the clickable replay links to users. Each session replay result includes a direct URL that users can click to view the full replay in Amplitude's Session Replay interface. These links are essential for users to actually watch and analyze the sessions. Simply providing raw session data without the viewing links is not helpful.

EXAMPLES:

• Segments: All users

segmentFilters: [{ "conditions": [] }]

• Segments: Experiment variant membership

segmentFilters: [ { "conditions": [ { "type": "property", "group_type": "User", "prop_type": "user", "prop": "gp:[Experiment] My Flag", "op": "is", "values": ["treatment"] } ] } ]

• Segments: Country = US and plan in {Pro, Enterprise}

segmentFilters: [ { "conditions": [ {"type":"property","group_type":"User","prop_type":"user","prop":"country","op":"is","values":["US"]}, {"type":"property","group_type":"User","prop_type":"user","prop":"plan","op":"is","values":["Pro","Enterprise"]} ] } ]

• Event counter: at least 1 Purchase event

eventCountFilters: [ { "count": "1", "operator": "greater or equal", "event": {"event_type": "Purchase", "filters": [], "group_by": []} } ]

• Event counter: >= 3 Page Viewed on pricing page

eventCountFilters: [ { "count": "3", "operator": "greater or equal", "event": { "event_type": "Page Viewed", "filters": [ { "group_type": "User", "subprop_key": "page", "subprop_op": "is", "subprop_type": "event", "subprop_value": ["pricing"] } ], "group_by": [] } } ]

NOTES:

• Prefer property-based segment conditions for attributes; prefer eventCountFilters for behavioral criteria.

Query up to 3 charts concurrently given their IDs.

RULES:

• Users want to know references for analyses in order to validate the data.
• ALWAYS REFERENCE CHARTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.

WHEN TO USE:

• You want to query multiple charts to get their data efficiently.
• Maximum of 3 charts can be queried in a single request.

INSTRUCTIONS:

• Use the search tool to find the IDs of the charts you want to query.
• Use this tool to query up to 3 charts.
• Results will include data for each successfully queried chart and errors for any failed charts.

RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse

CSV Response Structure (when isCsvResponse is true):

• Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details
• Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)
• Data rows: Each row contains:
• Label columns: First few columns contain row labels identifying the data series
• Value columns: Numerical data organized under the corresponding date/time columns from the data header row
• Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns
• Cells in the CSV response are delimited by commas and may be prepended with a character

Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'"

" Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", }

JSON Response Structure (when isCsvResponse is false):

• Parse using the following structure:
• timeSeries: Array of arrays, each containing data point for a given time period with a "value" property
• overallSeries: Array of arrays, each containing data the overall data point (across the entire range) under the "value" property
• seriesMetadata: Array of objects containing metadata for each series
• xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series
• Use the dataset definition to be able to parse referenced events, properties, and segments.

Example below is a JSON response is for the same query as the CSV example above. { "timeSeries": [[{"value": 614}, {"value": 1769}, {"value": 4132}]], "overallSeries": [[{"value": 5642}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "UNIQUES(A)"}], "xValuesForTimeSeries": ["2025-08-23T00:00:00", "2025-08-24T00:00:00", "2025-08-25T00:00:00"] }

Execute a data query using the dataset endpoint for more complex queries.

WHEN TO USE

• You want to query data to form an ad hoc analysis within a project that does not already exist as a chart, metric, or experiment.
• You want to tweak an existing chart to glean more information from it (e.g. add a group by, change the time range, etc.)

STRATEGIES

1. Use the 'search' tool to find existing charts that relate to the data you want to query. 2. Use the 'get_charts' tool to understand the events, properties, and dataset schema generally. 3. Optionally use the 'search' tool again to find additional events, user properties, etc. needed for the query. 4. Optionally use the 'get_event_properties' tool to get properties on individual events. 3. Use this tool to query the ad hoc analysis.

GENERAL GUIDELINES

• Don't assume or guess properties, events, or schema. Use the tools provided to you to understand the data before running a dataset query.
• When running into query failures, try searching for existing charts to understand the data taxonomy and dataset schema.
• When you receive a 400 error response the schema is likely incorrect or the events/properties do not exist.

AMPLITUDE WIDE META EVENTS TYPES

Special system events available for analysis. Events are passed in the "event_type" field:

• "_active": Any active event useful for tracking 'active users' like DAU, MAU(events not marked as inactive)
• "_all": Any event being tracked in Amplitude
• "_new": Events triggered by new users within the time interval. Useful for tracking 'new users'.
• "_any_revenue_event": Any revenue-generating event. Useful for tracking 'revenue'.
• "$popularEvents": Top events by volume (dynamically computed). Useful for more meta taxonomy analyses like 'what are the most common events'.

PROPERTY TYPES:

• AMPLITUDE CORE PROPERTIES: Built-in properties automatically tracked by Amplitude
• Have source: "AMPLITUDE"
• Use standard naming (lowercase, underscores)
• Available for all events and users
• CUSTOM PROPERTIES: Organization-defined properties
• Have source: "CUSTOMER"
• ALWAYS prefixed with "gp:" (e.g., "gp:email", "gp:full name")
• Include experiment flags like "gp:[Experiment] feature-name"

COMPLETE LIST OF AMPLITUDE CORE PROPERTIES:

User & Session Identification:

• user_id: Primary user identifier
• amplitude_id: Amplitude's internal user ID
• device_id: Unique device identifier
• session_id: Session identifier
• event_id: Unique event identifier

Geographic Properties:

• ip_address: User's IP address
• country: Country (from GeoIP)
• city: City (from GeoIP)
• region: State/region (from GeoIP)
• dma: Designated Market Area
• $postal_code: Postal/ZIP code
• location_lat: Latitude coordinate
• location_lng: Longitude coordinate

Device & Platform Properties:

• platform: Device platform (iOS, Android, Web, etc.)
• device: Device family name
• device_type: Type of device (mobile, tablet, desktop)
• os: Operating system
• language: Device language setting
• carrier: Mobile carrier

Application Properties:

• version: Current app version
• start_version: Version when user first used the app
• library: SDK library used to send data
• server_upload_time: When data was received by Amplitude

Business Properties:

• paying: Whether user is a paying customer

RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse

CSV Response Structure (when isCsvResponse is true):

• Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details
• Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)
• Data rows: Each row contains:
• Label columns: First few columns contain row labels identifying the data series
• Value columns: Numerical data organized under the corresponding date/time columns from the data header row
• Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns
• Cells in the CSV response are delimited by commas and may be prepended with a character

Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'"

" Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", }

JSON Response Structure (when isCsvResponse is false):

• Parse using the following structure:
• timeSeries: Array of arrays, each containing data point for a given time period with a "value" property
• overallSeries: Array of arrays, each containing data the overall data point (across the entire range) under the "value" property
• seriesMetadata: Array of objects containing metadata for each series
• xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series
• Use the dataset definition to be able to parse referenced events, properties, and segments.

Example below is a JSON response is for the same query as the CSV example above. { "timeSeries": [[{"value": 614}, {"value": 1769}, {"value": 4132}]], "overallSeries": [[{"value": 5642}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "UNIQUES(A)"}], "xValuesForTimeSeries": ["2025-08-23T00:00:00", "2025-08-24T00:00:00", "2025-08-25T00:00:00"] }

Query an experiment analysis.

CRITICAL: Do NOT pass metricIds unless user explicitly requests specific metrics or requests analysis on secondary metrics. Omit metricIds for primary metric only (cleaner, focused results).

RULES:

• Users want to know references for analyses in order to validate the data.
• ALWAYS REFERENCE EXPERIMENTS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.

WHEN TO USE:

• You want to query a experiment for analysis.

INSTRUCTIONS:

• Use the search tool to find the ID of the experiment you want to query.
• You may want to use the get_experiments tool to get more context about the experiment (i.e. state, variants, etc.)
• Use this tool to query the experiment analysis.

EXAMPLE: groupBy: [{"type": "user", "value": "device type", "group_type": "User"}]

Query metric data using the dataset endpoint with metric references

RULES:

• Users want to know references for analyses in order to validate the data.
• ALWAYS REFERENCE METRICS TO THE USER BY THEIR LINK WHEN QUERIED AND USED IN ANALYSES.

WHEN TO USE:

• You want to query a metric to get its data.

INSTRUCTIONS:

• Use the search tool to find the ID of the metric you want to query.
• Use this tool to query the metric.

RESPONSE FORMAT: Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present. Check the isCsvResponse flag to determine which response format to parse

CSV Response Structure (when isCsvResponse is true):

• Header rows: The top rows contain metadata including chart name, description, events, formulas, and other chart configuration details
• Data header row: A single row containing column labels for the data points below (typically includes dates or time periods)
• Data rows: Each row contains:
• Label columns: First few columns contain row labels identifying the data series
• Value columns: Numerical data organized under the corresponding date/time columns from the data header row
• Parse by: Skip metadata rows, identify the data header row, then extract labels from first columns and values from remaining columns
• Cells in the CSV response are delimited by commas and may be prepended with a character

Example below measures uniques of custom event "Valuable Tweaking" over 3 days (2025-08-23, 2025-08-24, 2025-08-25) for all users. The data points are 614, 1769, and 4132 for the 3 days respectively. data: " Example chart name" " Formula"," UNIQUES(A)" " A:"," [Custom] 'Valuable Tweaking'"

" Segment"," 2025-08-23"," 2025-08-24"," 2025-08-25" " All Non-Amplitude Users","614","1769","4132" definition: { "app": "APP_ID", "params": { "countGroup": "User", "end": 1756166399, "events": [ { "event_type": "ce:'Valuable Tweaking'", "filters": [], "group_by": [] } ], "groupBy": [], "interval": 1, "metric": "uniques", "segments": [], "start": 1755907200, }, "type": "eventsSegmentation", }

JSON Response Structure (when isCsvResponse is false):

• Parse using the following structure:
• timeSeries: Array of arrays, each containing data point for a given time period with a "value" property
• overallSeries: Array of arrays, each containing data the overall data point (across the entire range) under the "value" property
• seriesMetadata: Array of objects containing metadata for each series
• xValuesForTimeSeries: Array of strings representing the x-axis values (dates) for the time series
• Use the dataset definition to be able to parse referenced events, properties, and segments.

Example below is a JSON response is for the same query as the CSV example above. { "timeSeries": [[{"value": 614}, {"value": 1769}, {"value": 4132}]], "overallSeries": [[{"value": 5642}]], "seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "UNIQUES(A)"}], "xValuesForTimeSeries": ["2025-08-23T00:00:00", "2025-08-24T00:00:00", "2025-08-25T00:00:00"] }

Search for dashboards, charts, notebooks, experiments, and other content in Amplitude.

INSTRUCTIONS:

• Use this as your primary tool to discover and explore available analytics content before diving into specific analyses.
• If you are not sure what to search for, use the default search query.
• Do not specify appIds/projectIds in the input unless the user explicitly asks to search within a specific app/project.
• When searching for taxonomy entities like events, properties, etc. use higher limits (e.g. 100-200) to get more results as there are more important entities to search through.
• When searching for events, use the get_event_properties tool to get event properties on an individual event.

ADDITIONAL INFORMATION:

• Results are personalized to the user you are making the request on behalf of.
• Results do not include the full object definition. You will need to use other tools to get the full object definition when needed.
• Best practice is to query for a single entity type, unless the user's request is open ended.
• The response includes an isOfficial flag in contentMeta to identify content that has been marked as official by the organization.