---
title: "Get click-test heatmap"
method: GET
path: "/surveys/{id}/questions/{questionId}/heatmap"
tags: ["Surveys"]
---

# Get click-test heatmap

`GET /surveys/{id}/questions/{questionId}/heatmap`

## Request

- Base URL: `https://api.pickfu.com/v1`
- URL: `https://api.pickfu.com/v1/surveys/{id}/questions/{questionId}/heatmap`
- Auth: HTTP bearer

Returns a permanent CDN URL to a rendered heatmap PNG image for a click-test question. The heatmap composites all click data onto the original question image. Results are cached in Cloudinary — subsequent requests for the same click data return instantly. `regions` carries the click regions saved for the current image, with first-click counts from the same clicks, or null when the image has none.

### Prerequisites
- Question must be a `click-test` type
- Question must have at least one click response
- Returns 422 for non-click-test questions or questions with zero clicks

## Path parameters

- `id` string, required
- `questionId` string, required

## Response `200`

Default Response

- object
  - `heatmapUrl` string: Signed URL to the rendered heatmap PNG image
  - `regions` object, nullable: The question's click regions for its current image, counted from the same clicks the heatmap draws (first clicks, unfiltered); null when the image has none. GET /surveys/{id}/questions/{questionId}/click-regions describes the shape.
    - `imagePublicId` string: The question's current image
    - `revision` integer: The current revision for that image; 0 when none
    - `regions` object[]: Boxes as fractions of the image from its top left; empty when none
      - `key` string
      - `label` string, nullable
      - `x` number
      - `y` number
      - `w` number
      - `h` number
    - `source` string, nullable: `template` (seeded from a mockup template), `detected` or `drawn`; null when none
    - `counts` object
      - `mode` 'first' | 'all'
      - `respondents` integer: Respondents with at least one click, after filters
      - `clicks` integer: Clicks counted; equals `respondents` in `first` mode
      - `regions` object[]: One tally per region, in stored order
        - `key` string
        - `label` string, nullable
        - `count` integer
        - `share` integer: Whole percent of respondents (`first`) or clicks (`all`); the regions and `outside` sum to 100, or are all 0 with nothing counted
        - `ci95` object, nullable: Wilson 95% interval in percent, one decimal; null in `all` mode or with no respondents
          - `low` number
          - `high` number
      - `outside` object: Clicks outside every region
        - `count` integer
        - `share` integer: Whole percent of respondents (`first`) or clicks (`all`); the regions and `outside` sum to 100, or are all 0 with nothing counted
        - `ci95` object, nullable: Wilson 95% interval in percent, one decimal; null in `all` mode or with no respondents
          - `low` number
          - `high` number
      - `noClearWinner` boolean, nullable: A heuristic, not a significance test: true when the two most-clicked regions' intervals overlap (a tie always does), so no region should be called the winner yet. Null outside `first` mode, with fewer than two regions, or with no respondents.

## Other responses

- `401`: Default Response
- `403`: Default Response
- `404`: Default Response
- `422`: Default Response
- `500`: Default Response

---

[API](https://skmtc.dev/pickfu/apis/pickfu-api.md) · [All operations](https://skmtc.dev/pickfu/apis/pickfu-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pickfu/apis/pickfu-api/revisions/919fc58413ea?raw)