---
title: "Get a heatmap"
method: GET
path: "/v1/projects/{projectId}/heatmaps/{key}"
tags: ["Heatmaps"]
---

# Get a heatmap

`GET /v1/projects/{projectId}/heatmaps/{key}`

## Request

- Base URL: `https://hootlens-api-368877148687.us-east1.run.app`
- URL: `https://hootlens-api-368877148687.us-east1.run.app/v1/projects/{projectId}/heatmaps/{key}`
- Auth: HTTP bearer

Click density grid, pointer dwell, most-clicked elements and scroll depth for one cohort.

Required token scopes are listed in x-hootlens-scopes. A signed-in person needs the matching permission on the site instead (the viewer and editor roles are presets of the permissions).

## Path parameters

- `projectId` string, required: An identifier: 1 to 80 letters, digits, underscores or hyphens.
- `key` string, required

## Response `200`

The heatmap.

- HeatmapAggregate
  - `key` string, required: Cohort key. URL-encode it to use as a path parameter.
  - `group` string
  - `path` string, required
  - `buildId` string, required
  - `pageVersion` string
  - `revision` string, required
  - `variant` string, required
  - `deviceClass` 'desktop' | 'tablet' | 'mobile', required
  - `sessions` integer, required
  - `segments` integer, required
  - `clicks` integer, required
  - `lastSeenAt` integer, required: Epoch milliseconds.
  - `locales` object[]
    - `key` string
    - `segments` integer
    - `clicks` integer
  - `variants` object[]
    - `key` string
    - `segments` integer
    - `clicks` integer
  - `grid` object, required
    - `cellSize` integer, required
    - `cells` array[], required: Each cell is [column, row, count].
      - integer[]
  - `docWidth` integer, required
  - `docHeight` integer, required
  - `moves` object, required
    - `cellSize` integer, required
    - `cells` array[], required: Each cell is [column, row, weight]. Shows pointer position, not attention.
      - number[]
  - `selectors` object[], required: Most-clicked elements, at most 200.
    - `selector` string, required
    - `label` string
    - `name` string: The name the team gave this element, when it has one.
    - `source` string: Source file and line of the most recent click on this element in this cohort, such as `src/components/Pricing.tsx:42`, when the site uses the Hoot Lens build plugin.
    - `context` ElementContext: Short context recorded with a click. The strict preset records tag and region only.
      - `tag` string: Tag of the clicked element, such as div, li, p or img.
      - `region` string: The nearest region: a data-hoot-region, an ancestor data-hoot-id, a section with an id or aria-label, else the nearest landmark tag. At most 60 characters.
      - `heading` string: Text of the nearest h1 to h3 above the element. Full and balanced presets only; at most 60 characters.
      - `text` string: The element's own text, shortened. Full and balanced presets only; at most 60 characters.
    - `interactive` false: False when the element is not a link, button or other control. Absent otherwise.
    - `clicks` integer, required
    - `rageClicks` integer, required
    - `deadClicks` integer, required
    - `errorClicks` integer, required
  - `scrollDepths` number[], required: Share of page views reaching each 10% band of the page; index 0 is the top.
  - `reference` object
    - `recordingId` string
    - `timestamp` integer: Epoch milliseconds.

## Other responses

- `401`: The credential is missing, expired or revoked.
- `403`: The credential or the person's permissions on the site do not permit this action.
- `404`: The site, or the record inside it, does not exist or the caller is not a member (a non-member cannot tell the two apart).
- `429`: A rate limit or a per-site limit was reached.

---

[API](https://skmtc.dev/hootlens/apis/hoot-lens-api.md) · [All operations](https://skmtc.dev/hootlens/apis/hoot-lens-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hootlens/apis/hoot-lens-api/revisions/f64f8dc7b84e?raw)