---
title: "Get a page's heatmap"
method: GET
path: "/v1/sites/{siteId}/heatmaps"
tags: ["Heatmaps"]
---

# Get a page's heatmap

`GET /v1/sites/{siteId}/heatmaps`

## Request

- Base URL: `https://api.ironfang.com/analytics`
- URL: `https://api.ironfang.com/analytics/v1/sites/{siteId}/heatmaps`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Attention, scroll reach, clicks and movement for one page and device over a period, from at most 20,000 of its visits (a deterministic sample when there are more), with the visit to draw it over. Fewer than 30 visits is flagged small_sample. Needs analytics.sessions.read.

## Query parameters

- `path` string, required
- `bucket` 'mobile' | 'tablet' | 'desktop', required: By viewport width when the visit began, under 768, under 1280, and wider.
- `from` string, date-time
- `to` string, date-time

## Response `200`

Heatmap

- Heatmap
  - `background` HeatmapBackground, required
    - `duration_ms` integer, required: How long the visit lasted.
    - `epoch_index` integer, required
    - `layout_hash` string, nullable, required
    - `offset_ms` integer, required: Where the visit starts in its recording, in milliseconds from the recording's first event, as the replay player counts them.
    - `recording_id` string, uuid, required
    - `started_at` string, date-time, required
    - `viewport_height` integer, required
    - `viewport_width` integer, required
  - `backgrounds` HeatmapBackground[], required: The visits the heatmap can be drawn over, background first: of the most common layout, at a width near the period's median, and of those the ones that scrolled furthest. At most 5.
    - `duration_ms` integer, required: How long the visit lasted.
    - `epoch_index` integer, required
    - `layout_hash` string, nullable, required
    - `offset_ms` integer, required: Where the visit starts in its recording, in milliseconds from the recording's first event, as the replay player counts them.
    - `recording_id` string, uuid, required
    - `started_at` string, date-time, required
    - `viewport_height` integer, required
    - `viewport_width` integer, required
  - `bands` object, required
    - `attention_share` number[], required: Per band from the top, the share of a visit's time it was on screen.
    - `ms_per_visit` number[], required
    - `px` integer, required: The height of a band.
    - `reach` number[], required: Per band, the share of visits that scrolled to its bottom.
  - `bucket` 'mobile' | 'tablet' | 'desktop', required: By viewport width when the visit began, under 768, under 1280, and wider.
  - `clicks` object, required
    - `cell_px` integer, required
    - `cells` HeatmapCell[], required
      - number[]: [x, y, value]: x cells from the centre of the viewport (negative to the left), y cells from the top of the page (of the viewport for fixed clicks), and the value per visit.
    - `elements` object[], required: The targets most clicked, named without text.
      - `cells` HeatmapCell[], required: The located clicks in the page grid (the fixed grid when fixed), per visit. Drawing them inside the target's box instead, take these out of cells or fixed_cells so they are not counted twice.
        - number[]: [x, y, value]: x cells from the centre of the viewport (negative to the left), y cells from the top of the page (of the viewport for fixed clicks), and the value per visit.
      - `clicks` integer, required
      - `fixed` boolean, required: Whether most of its clicks landed on it while fixed or sticky. located, offsets and cells cover those clicks only.
      - `located` integer, required: How many of its clicks carry where within the target they landed (SDK 0.5.0).
      - `offsets` array[], required: A sample of the located clicks, where within the target each landed, 0 to 10000 across and down.
        - integer[]
      - `per_visit` number, required
      - `selector` string, required
    - `fixed_cells` HeatmapCell[], required
      - number[]: [x, y, value]: x cells from the centre of the viewport (negative to the left), y cells from the top of the page (of the viewport for fixed clicks), and the value per visit.
    - `fixed_per_visit` number, required: Clicks on fixed or sticky elements, which belong to the screen rather than a place on the page.
    - `per_visit` number, required
  - `from` string, date-time, required
  - `layouts` object[], required: The layouts seen, most common first.
    - `hash` string, nullable, required
    - `visits` integer, required
  - `moves` object, required
    - `cell_px` integer, required
    - `cells` HeatmapCell[], required: Milliseconds per visit the pointer rested in each cell.
      - number[]: [x, y, value]: x cells from the centre of the viewport (negative to the left), y cells from the top of the page (of the viewport for fixed clicks), and the value per visit.
  - `path` string, required
  - `sampled` integer, required: The visits the totals come from, at most 20000.
  - `seconds_on_screen` object, required
    - `mean` number, required
    - `median` number, required
  - `small_sample` boolean, required: Fewer than 30 visits.
  - `to` string, date-time, required
  - `visibility_known` number, required: The share of visits whose time excludes a hidden tab (SDK 0.5.0).
  - `visits` integer, required: Page visits in the period.

## Other responses

- `400`: An unknown, repeated or malformed query parameter (`invalid_query`).
- `401`: No credential, an invalid one, an expired partner integration key, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `api_key_expired`, `delegated_not_allowed`).
- `403`: The credential lacks the permission or scope, names another organisation, or belongs to a partner integration that is not active (`forbidden`, `insufficient_scope`, `integration_inactive`).
- `404`: No such object in this organisation (`not_found`).

---

[API](https://skmtc.dev/ironfang/apis/ironfang-analytics-api.md) · [All operations](https://skmtc.dev/ironfang/apis/ironfang-analytics-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ironfang/apis/ironfang-analytics-api/revisions/08197080c3d7?raw)