provider heatmaps GET /api/environments/{environment_id}/heatmaps/events/
@utdk/posthog /api/environments/{environment_id}/heatmaps/events/
environments_heatmaps_events_retrieve
Drill into the individual session interactions behind one or more heatmap coordinates. Pass the 'points' you want to inspect (from the heatmaps list response) to get the underlying per-session events, so you can jump to the session recordings that produced a hotspot.
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 interactions to return (1-100).
integer
offset query
Number of interactions to skip, for pagination.
integer
points query required
JSON array of the heatmap coordinates to drill into, e.g. '[{"x": 0.5, "y": 100}]'. Each point needs 'x' (relative x, 0..1) and 'y' (absolute client-y pixels) matching values returned by the heatmaps list endpoint; an optional 'target_fixed' boolean matches fixed-position elements. Returns the individual session interactions behind those spots.
string
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
environmentsHeatmapsEventsRetrieve
GET/api/environments/{environment_id}/heatmaps/events/
Drill into the individual session interactions behind one or more heatmap coordinates. Pass the 'points' you want to inspect (from the heatmaps list response) to get the underlying per-session events, so you can jump to the session recordings that produced a hotspot.

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 interactions to return (1-100).

Number of interactions to skip, for pagination.

required

JSON array of the heatmap coordinates to drill into, e.g. '[{"x": 0.5, "y": 100}]'. Each point needs 'x' (relative x, 0..1) and 'y' (absolute client-y pixels) matching values returned by the heatmaps list endpoint; an optional 'target_fixed' boolean matches fixed-position elements. Returns the individual session interactions behind those spots.

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.environmentsHeatmapsEventsRetrieve({
  "aggregation": "total_count",
  "date_from": "-7d",
  "hide_zero_coordinates": true,
  "limit": 50,
  "offset": 0,
  "type": "click"
})