---
title: Query scroll map
description: "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 obser…"
product: general
lang: en
last_updated: 2026-10-05
token_estimate: 2324
---
# Query scroll map

## Query scroll map

**POST** `/v1/projects/{project_id}/heatmaps/scroll-map`

Full URL: `https://developer-api.amplitude.com/v1/projects/{project_id}/heatmaps/scroll-map`

> 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`.

**Servers:**
- Production (US): `https://developer-api.amplitude.com/v1/projects/{project_id}/heatmaps/scroll-map`
- Production (EU): `https://developer-api.eu.amplitude.com/v1/projects/{project_id}/heatmaps/scroll-map`

Query 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.

## Authorizations

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| Authorization | string | Yes | — | http |

## Path parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| project_id (path) | string | Yes | 12345 | Amplitude project identifier, backed by the canonical app ID. Constraints: pattern: ^[0-9]+$ |

## Body (application/json)

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| page_url | string | Yes | https://example.com/pricing | 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. Constraints: min length: 1, max length: 2048 |
| url_match | string | No | is | 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. Allowed values: is, contains, has_prefix, glob |
| device_type | string | No | desktop | 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. Allowed values: desktop, laptop, tablet, mobile, custom |
| viewport_width | integer | No | — | Exact viewport width in pixels. Required when `device_type` is `custom` and not accepted otherwise. Constraints: min: 1, max: 20000 |
| time_range | object | No | — | — |
| time_range.start | string | Yes | — | Inclusive start date (project timezone unless `timezone` is set on query). Constraints: format: date |
| time_range.end | string | Yes | — | Inclusive end date. Constraints: format: date |

## Response (application/json)

**200** — Scroll map computed successfully.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| data | object | Yes | — | Scroll-depth distribution for one page, as a cumulative histogram from the top of the page. All buckets are returned in page order. Results reflect the caller's data access. |
| data.id | string | Yes | — | Identifier for this computation. |
| data.object | string | Yes | — | Resource-type discriminator. Always `scroll_map`. |
| data.project_id | string | Yes | — | Constraints: pattern: ^[0-9]+$ |
| data.page_url | string | Yes | — | The page URL after normalization. |
| data.url_match | string | Yes | is | 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. Allowed values: is, contains, has_prefix, glob |
| data.device_type | string | Yes | desktop | 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. Allowed values: desktop, laptop, tablet, mobile, custom |
| data.viewport_width | integer | Yes | — | Exact viewport width used when `device_type` is `custom`; otherwise `null`. Constraints: nullable |
| data.time_range | object | Yes | — | — |
| data.time_range.start | string | Yes | — | Inclusive start date (project timezone unless `timezone` is set on query). Constraints: format: date |
| data.time_range.end | string | Yes | — | Inclusive end date. Constraints: format: date |
| data.timezone | string | Yes | — | IANA timezone used to resolve `time_range` day boundaries (the project timezone). |
| data.total_sessions | integer | Yes | — | Sessions with a scroll event on the page in the range (the first bucket's count). Constraints: min: 0 |
| data.average_fold_px | integer | Yes | — | Average viewport height in pixels, or `null` when unavailable. Constraints: nullable |
| data.max_scroll_depth_px | integer | Yes | — | Deepest scroll position observed in page pixels, or `null` when unavailable. Constraints: nullable |
| data.bucket_count | integer | Yes | — | Constraints: min: 0 |
| data.buckets | object[] | Yes | — | — |
| data.buckets.depth_from_px | integer | Yes | — | Lower bound of the scroll-depth bucket in page pixels. Constraints: min: 0 |
| data.buckets.depth_to_px | integer | Yes | — | Upper bound of the scroll-depth bucket in page pixels. Constraints: min: 0 |
| data.buckets.sessions_reached | integer | Yes | — | Sessions that scrolled at least to this bucket. Constraints: min: 0 |
| data.buckets.percent_reached | number | Yes | — | `sessions_reached` divided by the sessions counted in the first bucket, as a fraction. The first bucket is always `1`. Constraints: min: 0, max: 1 |
| data.warnings | string[] | Yes | — | Non-fatal conditions, such as an empty result for the range. |

```json
{
  "data": {
    "id": "string",
    "object": "scroll_map",
    "project_id": "string",
    "page_url": "string",
    "url_match": "is",
    "device_type": "desktop",
    "viewport_width": 0,
    "time_range": {
      "start": "2024-01-01",
      "end": "2024-01-01"
    },
    "timezone": "string",
    "total_sessions": 0,
    "average_fold_px": 0,
    "max_scroll_depth_px": 0,
    "bucket_count": 0,
    "buckets": [
      {
        "depth_from_px": 0,
        "depth_to_px": 0,
        "sessions_reached": 0,
        "percent_reached": 0
      }
    ],
    "warnings": [
      "string"
    ]
  }
}
```

**400**

**401**

**403**

**404**

**422**

**429**

**500**

**502**

**503**

**504**

## Code samples

### cURL

```bash
curl -X POST "https://developer-api.amplitude.com/v1/projects/12345/heatmaps/scroll-map" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY"
```

### Python

```python
import requests

response = requests.post(
    "https://developer-api.amplitude.com/v1/projects/12345/heatmaps/scroll-map",
    headers={
        "Content-Type": "application/json",
        "Authorization": "YOUR_API_KEY"
    }
)
data = response.json()
```

### JavaScript

```javascript
const response = await fetch("https://developer-api.amplitude.com/v1/projects/12345/heatmaps/scroll-map", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "YOUR_API_KEY"
  }
});
const data = await response.json();
```

### PHP

```php
<?php
$ch = curl_init("https://developer-api.amplitude.com/v1/projects/12345/heatmaps/scroll-map");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: YOUR_API_KEY"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
```

### Go

```go
package main

import (
  "bytes"
  "net/http"
)

func main() {
req, _ := http.NewRequest("POST", "https://developer-api.amplitude.com/v1/projects/12345/heatmaps/scroll-map", nil)
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "YOUR_API_KEY")
  client := &http.Client{}
  resp, _ := client.Do(req)
  defer resp.Body.Close()
}
```

### Java

```java
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://developer-api.amplitude.com/v1/projects/12345/heatmaps/scroll-map"))
      .method("POST", HttpRequest.BodyPublishers.noBody())
.header("Content-Type", "application/json")
      .header("Authorization", "YOUR_API_KEY")
      .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
```

### Ruby

```ruby
require "net/http"
require "json"

uri = URI("https://developer-api.amplitude.com/v1/projects/12345/heatmaps/scroll-map")
request = Net::HTTP::Post.new(uri)
request["Content-Type"] = "application/json"
request["Authorization"] = "YOUR_API_KEY"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
```

