Query amplitude data
Run analytics queries to answer data questions about users, events, funnels, and retention — and to create or modify charts via the typed `chart` parameter.
PREFERRED: pass the typed `chart` parameter (segmentation | funnel | retention | sessions | data_table). It is a small, UI-shaped model (events, where, group_by, measured_as, segments, date_range) that is deterministically compiled server-side into a validated chart definition — compile errors come back with a fix-oriented hint, so you never need to hand-build raw definition JSON.
FALLBACK: pass a raw `definition` only for chart types the typed model does not cover (composition, revenueLtv) or advanced params the typed model has no field for. Raw definitions are validated inline; on failure the response includes chartTypeSchema with the parameter schema, valid enums, a working example, and coercion rules.
Provide exactly one of `chart` or `definition`.
# WHEN TO USE - Answer questions like:
- "How many active users did we have last week?"
- "Show me a funnel from sign up to purchase"
- "What is the retention rate for new users?"
- "Create a chart…" / "Modify chart X to…"
- Any question asking for metrics, counts, trends, funnels, or retention analysis
# DO NOT USE FOR:
- Finding existing charts/dashboards → use 'search' or 'get_amplitude_charts' instead
- Project settings (timezone, currency) → use 'get_amplitude_context' with projectId instead
# STRATEGIES
1. Discover event/property names with 'search' (or search_amp_data_taxonomy) — never guess them.
2. Create: build the typed `chart` (events + date_range required; add where/group_by/segments as asked) → call this tool.
3. Modify / fork a saved chart: `search` to find the chart id → `get_amplitude_charts include='typed'` → edit the returned `chart` → call this tool with that `chart` AND `chartId` set to the saved chart id (links the edit to the parent; parent params fill gaps the typed model omits — including `date_range`, which may be left out to keep the parent's window).
4. Call query_amplitude_data — compile and validation errors are actionable; fix the named field and retry.
5. To show the result visually, call 'render_amplitude_chart' with the returned chartEditId.
# GENERAL GUIDELINES
- Don't guess event or property names — discover them first, and use the exact name and scope returned.
- ALWAYS set a descriptive "name" (becomes the chart title) and an explicit date_range (except when modifying with chartId and the parent's window should be kept).
- Relative date_range windows support an Offset suffix for day-over-day / historical comparisons: "Last 0 Days Offset 1" (yesterday), "Last 0 Days Offset 7" (same day last week), "Last 7 Days Offset 7" (the prior week).
- On errors, follow the hint in the message; the compiler names the offending field.
Chart types supported by raw `definition`: eventsSegmentation, funnels, metricExplorer, retention, revenueLtv, sessions, stickiness
RESPONSE FORMAT:
Returns {isCsvResponse: bool, csvResponse or jsonResponse, definition}. Only ONE response type present.
When jsonResponse is present, "seriesNames" (string[]) gives the human-readable name of each timeSeries entry in order — use it instead of the numeric seriesLabels for ungrouped segments.
Check the isCsvResponse flag to determine which response format to parse
CRITICAL — NON-ADDITIVE METRICS (uniques, pct_dau):
- These metrics cannot be summed across intervals. The chart UI plots per-interval values, not a running total.
- Additive metrics (totals, sums) CAN be summed across intervals.
How to read the JSON response, by metric type:
1. COUNT metrics ("uniques"):
- Use "overallSeries" — it is the TRUE deduped unique count across the full date range.
- Do NOT sum "timeSeries" values — that overstates the count due to user overlap across intervals.
2. RATIO metrics ("pct_dau" only):
- Use "timeSeriesAverage" (mean of per-interval values) — this matches what the chart UI displays.
For "current" reporting, also consider the most recent N intervals from "timeSeries".
- Do NOT use "overallSeries" for pct_dau over multi-interval ranges. For pct_dau, "overallSeries"
is a long-range aggregate (deduped numerator over the full range / deduped denominator over the
full range). Over many intervals the denominator dedupes a much larger pool than the numerator,
which compresses the ratio — typically reporting roughly half of the per-interval values the chart
shows. This is mathematically valid as a long-range aggregate but is NOT what users see in the chart.
- Do NOT sum "timeSeries" values — ratios cannot be summed.
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.
IMPORTANT: The overall unique users is 5642 (NOT 614+1769+4132=6515), because users overlap across days.
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 points for a given time period with a "value" property
- overallSeries: Array of arrays, each containing the overall data point across the entire range under the "value" property.
IMPORTANT — interpretation depends on the metric:
* For "uniques" (count): this is the TRUE deduped unique count over the full date range. Use this.
* For "pct_dau" (ratio): this is a long-range aggregate ratio (deduped numerator
over range / deduped denominator over range). It does NOT match the per-interval values the
chart UI plots and is typically much smaller. Do NOT report it as the headline number — use
"timeSeriesAverage" instead.
- timeSeriesAverage: Present only for "pct_dau". Array of arrays, one per series, each
containing a single {value} that is the mean of "timeSeries" values for that series. Use this as the
headline ratio when the chart spans multiple intervals — it matches what users see in the chart UI.
- 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"]
}
Note: 614+1769+4132=6515, but overallSeries shows 5642. This is because unique users overlap across days. For "uniques", always use overallSeries for the total.
Example below is a "pct_dau" query over 3 weeks (a ratio metric):
{
"timeSeries": [[{"value": 0.1402}, {"value": 0.1421}, {"value": 0.1444}]],
"overallSeries": [[{"value": 0.0712}]],
"timeSeriesAverage": [[{"value": 0.1422}]],
"seriesMetadata": [{"segmentIndex": 0, "formulaIndex": 0, "formula": "PCT_DAU(A)"}],
"xValuesForTimeSeries": ["2026-04-06T00:00:00", "2026-04-13T00:00:00", "2026-04-20T00:00:00"]
}
Note: the chart UI shows ~14% per week. timeSeriesAverage (14.22%) matches that. overallSeries (7.12%) is the
deduped 3-week aggregate ratio and would HALVE the reported value if used as the headline — never report it
as "the number" for "pct_dau". Always use timeSeriesAverage for "pct_dau".
Event Segmentation with Insights (anomaly detection / confidence intervals):
- When params.insights.isOn is true, Event Segmentation charts queried via query_charts or query_dataset
return BOTH chartConfig (Highcharts) AND jsonResponse with joinable band data.
- jsonResponse.seriesIntervals maps stringified seriesMetadata keys to { low, high, yhat } arrays
(parallel to xValuesForTimeSeries). Use seriesMetadata + xValuesForTimeSeries to join bands to series.
- Metric Explorer charts with Insights return seriesIntervals inside each data[] entry instead.