provider heatmaps GET /api/environments/{environment_id}/heatmaps/
@utdk/posthog /api/environments/{environment_id}/heatmaps/
environments_heatmaps_list
Aggregated heatmap interactions for a page. For type 'click'/'rageclick'/'mousemove' each result is a point with relative x, absolute client-y, and a count. For type 'scrolldepth' the response is scroll-depth buckets instead (cumulative reach down the page).
aggregation query
How to aggregate counts: 'total_count' (every interaction, default) or 'unique_visitors' (distinct people). * `unique_visitors` - unique_visitors * `total_count` - total_count
enum: unique_visitors, total_count
cohort_ids query
JSON array of cohort IDs (e.g. '[123, 456]') to restrict results to people in those cohorts. Feature-flagged; ignored when the cohort filter is not enabled for the caller.
stringnull
date_from query
Start of the window. Relative (e.g. '-7d', '-30d', '-1mStart') or an absolute 'YYYY-MM-DD' date. Defaults to '-7d'. Heatmap data is retained for 90 days.
string
date_to query
End of the window, inclusive. Relative or absolute 'YYYY-MM-DD'. Defaults to today.
string
environment_id path required
Deprecated. Use /api/projects/{project_id}/ instead.
string
filter_test_accounts query
When true, exclude sessions from internal/test accounts using the project's test-account filters.
booleannull
hide_zero_coordinates query
When true (default), drop interactions recorded at the (0, 0) origin, which are usually noise.
boolean
limit query
Maximum number of coordinate points to return, ordered hottest-first by count. Defaults to 500. Pass 0 to fetch the full set (every coordinate) needed to render a complete heatmap overlay. Ignored for the 'scrolldepth' type, which always returns every bucket.
integer
offset query
Number of hottest-first points to skip, for paging through cooler coordinates. Ignored for the 'scrolldepth' type.
integer
type query
The interaction type to return. One of: 'click' (default), 'rageclick', 'mousemove', or 'scrolldepth'. Scrolldepth returns scroll buckets instead of x/y coordinates.
string
url_exact query
Match a single page by exact URL (trailing slash is ignored). Mutually exclusive with url_pattern.
string
url_pattern query
Match pages by regex against the full current_url (anchored automatically). Use this to aggregate across query strings or path segments. Mutually exclusive with url_exact.
string
viewport_width_max query
Only include interactions captured at a viewport at most this wide, in CSS pixels.
integer
viewport_width_min query
Only include interactions captured at a viewport at least this wide, in CSS pixels. Use with viewport_width_max to isolate a device class (e.g. 360-768 for mobile).
integer

Try it

Authentication
Configure credentials for PostHog API
environmentsHeatmapsList
GET/api/environments/{environment_id}/heatmaps/
Aggregated heatmap interactions for a page. For type 'click'/'rageclick'/'mousemove' each result is a point with relative x, absolute client-y, and a count. For type 'scrolldepth' the response is scroll-depth buckets instead (cumulative reach down the page).

Parameters

required

Deprecated. Use /api/projects/{project_id}/ instead.

How to aggregate counts: 'total_count' (every interaction, default) or 'unique_visitors' (distinct people). * `unique_visitors` - unique_visitors * `total_count` - total_count

JSON array of cohort IDs (e.g. '[123, 456]') to restrict results to people in those cohorts. Feature-flagged; ignored when the cohort filter is not enabled for the caller.

Start of the window. Relative (e.g. '-7d', '-30d', '-1mStart') or an absolute 'YYYY-MM-DD' date. Defaults to '-7d'. Heatmap data is retained for 90 days.

End of the window, inclusive. Relative or absolute 'YYYY-MM-DD'. Defaults to today.

When true, exclude sessions from internal/test accounts using the project's test-account filters.

When true (default), drop interactions recorded at the (0, 0) origin, which are usually noise.

Maximum number of coordinate points to return, ordered hottest-first by count. Defaults to 500. Pass 0 to fetch the full set (every coordinate) needed to render a complete heatmap overlay. Ignored for the 'scrolldepth' type, which always returns every bucket.

Number of hottest-first points to skip, for paging through cooler coordinates. Ignored for the 'scrolldepth' type.

The interaction type to return. One of: 'click' (default), 'rageclick', 'mousemove', or 'scrolldepth'. Scrolldepth returns scroll buckets instead of x/y coordinates.

Match a single page by exact URL (trailing slash is ignored). Mutually exclusive with url_pattern.

Match pages by regex against the full current_url (anchored automatically). Use this to aggregate across query strings or path segments. Mutually exclusive with url_exact.

Only include interactions captured at a viewport at most this wide, in CSS pixels.

Only include interactions captured at a viewport at least this wide, in CSS pixels. Use with viewport_width_max to isolate a device class (e.g. 360-768 for mobile).

Configure credentials above to enable sending.

Code snippet
Updates live as you fill in the form above.

TypeScript

import posthog from '@utdk/posthog';

await posthog.environmentsHeatmapsList({
  "aggregation": "total_count",
  "date_from": "-7d",
  "hide_zero_coordinates": true,
  "limit": 500,
  "offset": 0,
  "type": "click"
})