---
title: "Get a session's heatmap"
method: GET
path: "/v1/sessions/{sessionId}/heatmap"
tags: ["Sessions"]
---

# Get a session's heatmap

`GET /v1/sessions/{sessionId}/heatmap`

## Request

- Base URL: `https://api.ironfang.com/analytics`
- URL: `https://api.ironfang.com/analytics/v1/sessions/{sessionId}/heatmap`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Attention, scroll reach, clicks and movement on one page from this session's visits alone, every tab's, drawn over its own recording; the same figures as a site's heatmap. Heatmaps come from recordings, extracted once each ends, so a page the session did not record, or whose recording is still open, expired or deleted, has none. Needs analytics.sessions.read.

## Query parameters

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

## Response `200`

The session's heatmap

- SessionHeatmap
  - `heatmap` Heatmap, required
    - `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.
  - `pages` HeatmapPage[], required: The pages with a heatmap, in the order the session first came to them, by device.
    - `desktop` integer, required
    - `mobile` integer, required
    - `path` string, required
    - `tablet` integer, required
    - `visits` integer, required

## 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)