For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

Query chart

Computes and returns normalized results for a saved chart. v1 supports
event_segmentation, sessions, funnels, and retention chart types;
other chart types return 422 with error_code: unsupported_chart_type.
Results reflect the authenticated caller's project access and chart
permissions.

This POST computes a result and does not mutate state. It is therefore a
read operation and does not require an Idempotency-Key.

Omitting time_range uses the chart's saved range; if the chart has no
saved range, the server defaults to the last 30 days.

Query is synchronous with bounded defaults. Expensive queries may return
504 when exceeding the server timeout; async query jobs are planned for
a follow-up slice. Retryable responses may include retry advice where
their endpoint-specific error contract provides it.

post/v1/projects/{project_id}/charts/{chart_id}/query

Authorizations

Authorizationstringrequired

http

Path parameters

project_idstringrequired

Amplitude project identifier, backed by the canonical app ID.

Example:12345
Constraints:pattern: ^[0-9]+$
chart_idstringrequired

Saved chart identifier.

Constraints:min length: 1

Body

application/json
time_rangeobject
Show child attributes
startstringrequired

Inclusive start date (project timezone unless timezone is set on query).

Constraints:format: date
endstringrequired

Inclusive end date.

Constraints:format: date
timezonestring

IANA timezone identifier (e.g. America/New_York).

Example:America/New_York
exclude_incomplete_datapointsboolean

When true, excludes the current incomplete interval from results.

Default:false
group_by_limitinteger

Maximum number of breakdown groups returned per series.

Default:10
Constraints:min: 1max: 1000
time_series_limitinteger

Maximum number of time buckets per series. 0 collapses each series to a single scalar aggregate.

Default:100
Constraints:min: 0max: 1000

Response

application/json
200· Query completed successfully.
dataobjectrequired
Show child attributes
idstringrequired

Identifier for this query execution.

objectstringrequired

Resource-type discriminator. Always analytics_result.

source_typestringrequired

Source artifact type. v1 supports chart only. dashboard and query are reserved for future slices.

Allowed values:chart
source_idstringrequired

Identifier of the source chart.

project_idstringrequired
Constraints:pattern: ^[0-9]+$
computed_atstringrequired
Constraints:format: date-time
timezonestringrequired

IANA timezone used for computation.

result_kindstringrequired

High-level shape of the normalized result payload. Adapters set this explicitly per supported chart type; unknown means the server could not classify the result shape safely.

Allowed values:timeseriesscalarfunnelretentiontableunknown
metric_semanticsobjectrequired
additivebooleanrequired

When false, values must not be summed across time intervals or groups without understanding deduplication semantics.

recommended_aggregatestringrequired

Recommended aggregation method for downstream consumers. Non-additive metrics (e.g. unique users) must not be summed across intervals. unknown is used when the adapter cannot determine a safe aggregate; treat values as non-additive in that case.

Allowed values:sumlastmeandeduped_totalnoneunknown
notesstring

Human-readable guidance for interpreting values.

Constraints:nullable
dataobjectrequired

Normalized result payload. Populated fields depend on result_kind. Timeseries and funnel results use dimensions and series. Table results use columns and rows.

dimensionsobject[]
idstringrequired
labelstringrequired
rolestringrequired

Role of this dimension in the result.

Allowed values:timesegmentbreakdownstep
seriesobject[]
idstringrequired
labelstringrequired
pointsobject[]required
xoneOfrequired

Dimension value (typically an ISO date or category label).

Constraints:stringnumber
ynumberrequired

Metric value at this point.

Constraints:nullable
completeboolean

When false, the interval is incomplete (current bucket). Only present when exclude_incomplete_datapoints is false.

aggregateobject

Optional pre-computed aggregate for the series.

valuenumberrequired
Constraints:nullable
methodstringrequired
columnsstring[]

Column headers for table-shaped results.

rowsoneOf[][]
metadataobjectrequired

Echo of effective query parameters and chart context.

chart_typestring

Public chart type discriminator (snake_case). All values may appear on list/get; query returns 422 (unsupported_chart_type) for types outside the v1 supported matrix.Unsupported or unrecognized chart types are surfaced as unknown.New chart types may be added over time. Clients should treat unknown as "a chart type this API version does not model yet".

Allowed values:event_segmentationsessionsfunnelsretentioncompositionrevenue_ltvstickinessdata_tableengagement_matrixmetric_explorergrowth_accountingimpactusersunknown
chart_namestring
time_rangeobject
startstringrequired

Inclusive start date (project timezone unless timezone is set on query).

Constraints:format: date
endstringrequired

Inclusive end date.

Constraints:format: date
exclude_incomplete_datapointsboolean
group_by_limitinteger
time_series_limitinteger
warningsstring[]required

Non-fatal issues encountered during query execution.

truncatedoneOf
Constraints:objectnull
group_by_limitinteger

Applied group-by limit when breakdown was truncated.

time_series_limitinteger

Applied time-series limit when buckets were truncated.

reasonstring

Human-readable explanation of truncation.

422· Chart type is not supported for public query in this version. The request was understood but cannot be processed. Returned with error_code: unsupported_chart_type; detail names the chart type and the currently supported set.
typestringrequired
Constraints:format: uri
titlestringrequired
statusintegerrequired
Constraints:min: 400max: 599
detailstring
Constraints:nullable
instancestring
Constraints:format: urinullable
error_codestringrequired
retryablebooleanrequired
retry_after_secondsinteger
Constraints:nullablemin: 0
validation_errorsobject[]
Constraints:nullable
504· Query exceeded the synchronous timeout.
typestringrequired
Constraints:format: uri
titlestringrequired
statusintegerrequired
Constraints:min: 400max: 599
detailstring
Constraints:nullable
instancestring
Constraints:format: urinullable
error_codestringrequired
retryablebooleanrequired
retry_after_secondsinteger
Constraints:nullablemin: 0
validation_errorsobject[]
Constraints:nullable

Was this helpful?