GuidesSupport
Web AnalyticsAttributionCookie ConsentA/B Testing & ExperimentationMapsTag ManagerSession ReplayTranslation WidgetHeatmapsPlatformIngest

Heatmaps

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

Authorization

apiKey
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}$
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" | "DEAD_RATE" | "ISSUE_SCORE" | "RAGE_RATE"
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://app.oursprivacy.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
  }
}
{
  "error": "string",
  "details": "string"
}
{
  "error": "string",
  "details": "string"
}
{
  "error": "string",
  "details": "string"
}
{
  "error": "string",
  "details": "string"
}
{
  "error": "string",
  "details": "string"
}
GET
/rest/v1/heatmap-pages/summary

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

pageKey*string

Page identifier returned by GET /rest/v1/heatmap-pages. Origin + pathname with the query string stripped (e.g. https://example.com/pricing).

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"desktop" | "mobile" | "tablet"
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}$
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://app.oursprivacy.com/rest/v1/heatmap-pages/summary?pageKey=https%3A%2F%2Fexample.com%2Fpricing&breakpoint=desktop&from=2026-04-01&to=2026-04-30"
{
  "clickBins": [
    {
      "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": "desktop",
      "url": "https://app.oursprivacy.com/session-replay/replayer?sessionId=sess_01HZX8YJH3Z3W1R2Q4M5N6P7Q8&visitorId=v_01HZX8TK6TSN91C5XWZP3N1M4E&date=2026-05-01"
    }
  ]
}
{
  "error": "string",
  "details": "string"
}
{
  "error": "string",
  "details": "string"
}
{
  "error": "string",
  "details": "string"
}
{
  "error": "string",
  "details": "string"
}
{
  "error": "string",
  "details": "string"
}

How is this guide?

Replay Settings

Previous Page

Versions

Next Page