---
title: amp heatmaps
description: "Reference for amp heatmaps click-map and scroll-map, which return click and scroll-depth data for a page URL."
product: general
lang: en
last_updated: 2026-11-18
token_estimate: 1196
---
# amp heatmaps

`amp heatmaps` returns click map and scroll map data for one page URL. This read-only command family requires the `analytics:read` scope.

## `amp heatmaps click-map`

Returns click counts for one page URL, grouped by the CSS selector of the clicked element or by page coordinate, ranked by count. Filter by device viewport band and date range. Results reflect the authenticated caller's project access and data access controls.

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

This POST computes a result and does not mutate state. It is therefore a read operation and does not require an `Idempotency-Key`.

Omitting `time_range` uses the last 30 days in the project timezone. The span of `time_range` cannot exceed 90 days.

```bash
amp heatmaps click-map --project <project_id> --page-url https://example.com/pricing --limit 25
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--page-url` | string | Yes | Page URL to analyze. Accepts `http` and `https` URLs; a URL without a scheme is treated as `https`. The query string and fragment are removed before matching, so `https://example.com/pricing?utm=x` and `https://example.com/pricing` are the same page. Alias: `--url`. |
| `--url-match` | string: `is`, `contains`, `has_prefix`, `glob` | No | How `page_url` is matched against the page URL recorded on each event. `is` matches the exact URL, `contains` matches any URL containing it, `has_prefix` matches URLs starting with it, and `glob` treats `*` as a wildcard. Alias: `--match`. |
| `--device-type` | string: `desktop`, `laptop`, `tablet`, `mobile`, `custom` | No | Viewport band to include, matching the device selector in the product: `desktop` is at least 1440 px wide, `laptop` is 900 to 1440 px, `tablet` is 500 to 900 px, `mobile` is at most 500 px. Use `custom` with `viewport_width` to match one exact width. Alias: `--device`. |
| `--viewport-width` | integer | No | Exact viewport width in pixels. Required when `device_type` is `custom` and not accepted otherwise. |
| `--time-range` | object | No |  |
| `--group-by` | string: `selector`, `pixel` | No | `selector` groups clicks by the CSS selector of the clicked element; `pixel` groups them by page coordinate. |
| `--metric` | string: `totals`, `uniques` | No | `totals` counts every click; `uniques` counts distinct users who clicked. |
| `--limit` | integer | No | Maximum number of rows returned after ranking by `count`. |

Requires the `analytics:read` scope.

## `amp heatmaps scroll-map`

Returns the scroll-depth distribution for one page URL as a cumulative histogram from the top of the page, plus the average fold and the deepest scroll observed. Filter by device viewport band and date range. Results reflect the authenticated caller's project access and data access controls.

This POST computes a result and does not mutate state. It is therefore a read operation and does not require an `Idempotency-Key`.

Omitting `time_range` uses the last 30 days in the project timezone. The span of `time_range` cannot exceed 90 days.

```bash
amp heatmaps scroll-map --project <project_id> --page-url https://example.com/pricing --device mobile
```

| Flag | Type | Required | Description |
| --- | --- | --- | --- |
| `--project` | string | Yes | Amplitude project identifier, backed by the canonical app ID. Alias: `--project-id`. |
| `--page-url` | string | Yes | Page URL to analyze. Accepts `http` and `https` URLs; a URL without a scheme is treated as `https`. The query string and fragment are removed before matching, so `https://example.com/pricing?utm=x` and `https://example.com/pricing` are the same page. Alias: `--url`. |
| `--url-match` | string: `is`, `contains`, `has_prefix`, `glob` | No | How `page_url` is matched against the page URL recorded on each event. `is` matches the exact URL, `contains` matches any URL containing it, `has_prefix` matches URLs starting with it, and `glob` treats `*` as a wildcard. Alias: `--match`. |
| `--device-type` | string: `desktop`, `laptop`, `tablet`, `mobile`, `custom` | No | Viewport band to include, matching the device selector in the product: `desktop` is at least 1440 px wide, `laptop` is 900 to 1440 px, `tablet` is 500 to 900 px, `mobile` is at most 500 px. Use `custom` with `viewport_width` to match one exact width. Alias: `--device`. |
| `--viewport-width` | integer | No | Exact viewport width in pixels. Required when `device_type` is `custom` and not accepted otherwise. |
| `--time-range` | object | No |  |

Requires the `analytics:read` scope.

