Query click map
Returns click counts for one page URL, grouped by the CSS selector of the
clicked element or by page coordinate, ranked by count. Filter by device
viewport band and date range. Results reflect the authenticated caller's
project access and data access controls.
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 last 30 days in the project timezone. The
span of time_range cannot exceed 90 days.
/v1/projects/{project_id}/heatmaps/click-mapAuthorizations
Authorizationstringrequiredhttp
Path parameters
project_idstringrequiredAmplitude project identifier, backed by the canonical app ID.
12345pattern: ^[0-9]+$Body
application/jsonpage_urlstringrequiredPage URL to analyze. Accepts http and https URLs; a URL without a
scheme is treated as https. The query string and fragment are removed
before matching, so https://example.com/pricing?utm=x and
https://example.com/pricing are the same page.
https://example.com/pricingmin length: 1max length: 2048url_matchstringHow page_url is matched against the page URL recorded on each event.
is matches the exact URL, contains matches any URL containing it,
has_prefix matches URLs starting with it, and glob treats * as a
wildcard.
iscontainshas_prefixglobisdevice_typestringViewport band to include, matching the device selector in the product:
desktop is at least 1440 px wide, laptop is 900 to 1440 px, tablet
is 500 to 900 px, mobile is at most 500 px. Use custom with
viewport_width to match one exact width.
desktoplaptoptabletmobilecustomdesktopviewport_widthintegerExact viewport width in pixels. Required when device_type is custom
and not accepted otherwise.
min: 1max: 20000time_rangeobjectShow child attributes
startstringrequiredInclusive start date (project timezone unless timezone is set on query).
format: dateendstringrequiredInclusive end date.
format: dategroup_bystringselector groups clicks by the CSS selector of the clicked element;
pixel groups them by page coordinate.
selectorpixelselectormetricstringtotals counts every click; uniques counts distinct users who
clicked.
totalsuniquestotalslimitintegerMaximum number of rows returned after ranking by count.
50min: 1max: 200Response
application/jsondataobjectrequiredRanked click counts for one page. Exactly one of selectors and pixels
is populated, chosen by group_by; the other is null. Rows are sorted
by count descending. Results reflect the caller's data access.
Show child attributes
idstringrequiredIdentifier for this computation.
objectstringrequiredResource-type discriminator. Always click_map.
project_idstringrequiredpattern: ^[0-9]+$page_urlstringrequiredThe page URL after normalization.
url_matchstringrequiredHow page_url is matched against the page URL recorded on each event.
is matches the exact URL, contains matches any URL containing it,
has_prefix matches URLs starting with it, and glob treats * as a
wildcard.
iscontainshas_prefixglobisdevice_typestringrequiredViewport band to include, matching the device selector in the product:
desktop is at least 1440 px wide, laptop is 900 to 1440 px, tablet
is 500 to 900 px, mobile is at most 500 px. Use custom with
viewport_width to match one exact width.
desktoplaptoptabletmobilecustomdesktopviewport_widthintegerrequiredExact viewport width used when device_type is custom; otherwise null.
nullablegroup_bystringrequiredselectorpixelmetricstringrequiredtotalsuniquestime_rangeobjectrequiredstartstringrequiredInclusive start date (project timezone unless timezone is set on query).
format: dateendstringrequiredInclusive end date.
format: datetimezonestringrequiredIANA timezone used to resolve time_range day boundaries (the project timezone).
result_countintegerrequiredNumber of rows returned.
min: 0truncatedbooleanrequiredtrue when more rows were available than limit allowed. The
underlying query is itself bounded, so false does not guarantee
that every clicked element on the page is listed.
selectorsobject[]requirednullablepixelsobject[]requirednullablewarningsstring[]requiredNon-fatal conditions, such as an empty result for the range.
Was this helpful?
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.