CDPGuidesSupport

Heatmaps

Inspect heatmap coverage across your site. List pages with click activity in a date window, then pull a rollup for a single page: click bins, dead clicks, rage clicks, scroll depth, and curated session replay links.

Inspect heatmap coverage across your site. List pages with click activity in a date window, then pull a bundled rollup for a single page including click bins, dead clicks, rage clicks, scroll depth, and curated session replay links.

GET/rest/v1/heatmap-pages

GET
/rest/v1/heatmap-pages

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

limit?|

Maximum number of items to return. Defaults to 25; values below 1 are clamped to 1 and values above 100 are clamped to 100.

cursor?string

Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request.

from*string

Inclusive lower bound of the heatmap window, as a UTC calendar day in YYYY-MM-DD format. The window between from and to must be 60 days or fewer.

Match^\d{4}-\d{2}-\d{2}$
to*string

Inclusive upper bound of the heatmap window, as a UTC calendar day in YYYY-MM-DD format. The window between from and to must be 60 days or fewer.

Match^\d{4}-\d{2}-\d{2}$
queryParameterFilter?string

Filter heatmap events by one URL query parameter, such as {"name":"p","values":["Contact Details"]}. Send as JSON in an HTTP query string and as an object in MCP. Matches any listed decoded value; values: [] matches any non-empty value. Apply the same filter to the list and summary. Works on retained historical events containing the parameter, requires no account setting, and does not change web-analytics page paths.

country?string

Filter by visitor country (ISO country name or code as stored on events).

Length1 <= length <= 128
region?string

Filter by visitor region (state/province as stored on events).

Length1 <= length <= 128
browserName?string

Filter by browser name as captured on events.

Length1 <= length <= 128
search?string

Case-insensitive substring match against pageKey.

Length1 <= length <= 256
sortBy?string

Sort key. Defaults to CLICKS (descending).

Value in

  • "CLICKS"
  • "RAGE_RATE"
  • "DEAD_RATE"
  • "ISSUE_SCORE"
sortDir?string

Sort direction. Defaults to DESC.

Value in

  • "ASC"
  • "DESC"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/heatmap-pages?from=2026-04-01&to=2026-04-30"
{  "entities": [    {      "pageKey": "https://example.com/pricing",      "totalClicks": 0,      "rageClicks": 0,      "deadClicks": 0,      "rageRate": 0,      "deadRate": 0,      "issueScore": 0,      "breakpoints": [        {          "breakpoint": "string",          "clicks": 0        }      ]    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  }}

GET/rest/v1/heatmap-pages/summary

GET
/rest/v1/heatmap-pages/summary

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

pageKey*string

Base page identifier returned by the heatmap pages list. Pass it unchanged, together with the same queryParameterFilter to inspect the same survey step. A legacy saved split key is accepted only without queryParameterFilter; combining them returns 400.

Length1 <= length <= 2048
breakpoint*string

Viewport bucket the click, dead-click, rage, and scroll-depth aggregations are computed for. Replays are returned for all breakpoints regardless of this value so callers can compare across devices.

Value in

  • "mobile"
  • "tablet"
  • "desktop"
from*string

Inclusive lower bound of the heatmap window, as a UTC calendar day in YYYY-MM-DD format. The window between from and to must be 60 days or fewer.

Match^\d{4}-\d{2}-\d{2}$
to*string

Inclusive upper bound of the heatmap window, as a UTC calendar day in YYYY-MM-DD format. The window between from and to must be 60 days or fewer.

Match^\d{4}-\d{2}-\d{2}$
queryParameterFilter?string

Filter heatmap events by one URL query parameter, such as {"name":"p","values":["Contact Details"]}. Send as JSON in an HTTP query string and as an object in MCP. Matches any listed decoded value; values: [] matches any non-empty value. Apply the same filter to the list and summary. Works on retained historical events containing the parameter, requires no account setting, and does not change web-analytics page paths.

country?string

Filter by visitor country (ISO country name or code as stored on events).

Length1 <= length <= 128
region?string

Filter by visitor region (state/province as stored on events).

Length1 <= length <= 128
browserName?string

Filter by browser name as captured on events.

Length1 <= length <= 128

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/heatmap-pages/summary?pageKey=https%3A%2F%2Fexample.com%2Fpricing&breakpoint=mobile&from=2026-04-01&to=2026-04-30"
{  "clickBins": [    {      "binX": 0,      "binY": 0,      "clicks": 0    }  ],  "clickGrid": {    "columns": 64,    "rows": 512,    "bins": [      {        "binX": 0,        "binY": 0,        "clicks": 0      }    ]  },  "deadClicks": [    {      "binX": 0,      "binY": 0,      "deadClicks": 0,      "topElement": "string"    }  ],  "rageClicks": [    {      "binX": 0,      "binY": 0,      "rageEvents": 0,      "totalClicks": 0    }  ],  "scrollDepth": [    {      "bucket": 0,      "sessions": 0    }  ],  "replays": [    {      "breakpoint": "mobile",      "url": "https://app.oursprivacy.com/session-replay/replayer?sessionId=sess_01HZX8YJH3Z3W1R2Q4M5N6P7Q8&visitorId=v_01HZX8TK6TSN91C5XWZP3N1M4E&date=2026-05-01"    }  ]}

How is this guide?

Journey Flows

Previous Page

Locations

Next Page