tracking_heatmaps_get

Tool

tracking_heatmaps_get

Get the heatmap of one page for one device: where visitors clicked (per element, on a 50x50 grid inside it), how far they scrolled, and which recording to draw the page from.

Get the heatmap of one page for one device: where visitors clicked (per element, on a 50x50 grid inside it), how far they scrolled, and which recording to draw the page from. sessions counts the recordings of the period and filters with a click or a scroll sample on the page — the same recordings tracking_recordings_list returns with the same device, campaign, source and conversion filters. scroll.reached[i] is a share of the sessions that reported a scroll depth on the page (a click-only session reports none), reaching (i+1)*5% of its height. Below 10 sessions the map is withheld: belowThreshold is true, clicks and scroll.reached are empty. Returns: { sessions, belowThreshold, clicks, scroll, background }. Fails when: the period is longer than 30 days; the call carries no product.

Behavior

HTTP: GET /tracking/heatmaps/page

Arguments

Name	Type	Required	Description
to	string	•	End of the period, ISO 8601: recordings that started at or before it.
from	string	•	Start of the period, ISO 8601 (e.g. 2026-10-01T00:00:00Z): recordings that started at or after it. At most 30 days before `to`.
device	string	•	Required: a map is drawn for one kind of device (desktop, tablet or mobile), since layouts differ.
pageKey	string	•	The page, as tracking_heatmaps_pages returns it: host + normalized path, e.g. shop.example.com/pricing.
converted	boolean	—	true: only sessions with a conversion or a payment; false: only sessions without one. Omit for both.
utmSource	string	—	Only recordings whose entry page carried this utm_source, e.g. google.
utmCampaign	string	—	Only recordings whose entry page carried this utm_campaign, e.g. spring.

Response

Field	Type	Always	Description
clicks	array	•	At most 300 elements, most clicked first.
scroll	object	•	How far down the page the sessions scrolled.
sessions	integer	•	Recordings of the period, device and filters with a click or a scroll sample on this page.
background	object	•	The latest recording of this device (any time in retention) whose segment loaded this page with a full snapshot at its start. Null when none: a page only ever reached by in-app navigation has no picture of its own.
belowThreshold	boolean	•	True when sessions < 10: clicks and scroll.reached are then empty and medianDocHeight null.

Try it

Get the heatmap of one page for one device: where visitors clicked (per element, on a 50x50 grid inside it), how far they scrolled, and which recording to draw the page from.

When to use

Example

Ask your agent something like this:

Get the heatmap of one page for one device: where visitors clicked (per element, on a 50x50 grid inside it), how far they scrolled, and which recording to draw the page from.

The agent will invoke tracking_heatmaps_get with these arguments:

{
  "to": "<to>",
  "from": "<from>",
  "device": "<device>",
  "pageKey": "<pageKey>"
}