assessing-heatmaps

You need an exact url_exact (one page) or a url_pattern (regex, to aggregate across query strings). Confirm the URL with the user if ambiguous. Default to the last 7 days; widen to 30 if volume is low. Heatmap data is retained for 90 days.

Call heatmaps-list once per signal you care about (or query the heatmaps table directly via SQL — see the querying-posthog-data skill, models-heatmaps):

• type: "click" — the primary "what draws attention" map.
• type: "rageclick" — repeated frustrated clicks. The single strongest "something is broken or misleading" signal. Any meaningful rageclick cluster deserves a callout.
• type: "scrolldepth" — how far people get. Use it to find the fold and spot CTAs that sit below where most people ever scroll.

Use aggregation: "unique_visitors" when you care about how many people (not how many clicks); total_count exaggerates a few heavy clickers.

Click results come back hottest-first and are capped at limit (default 500). A busy page can have thousands of distinct coordinates, so the default page plus the fold summary is almost always enough — the hottest points are what analysis turns on. Don't ask for everything: raise limit or page with offset only when you specifically need more, and check has_more to know the list was truncated. scrolldepth ignores limit and always returns every bucket.

For the click types, heatmaps-list returns a fold object alongside results:

• pct_below_fold — share of non-fixed interactions that landed below the user's initial viewport (they had to scroll to reach them). This is one of the highest-value findings: content people actively click that sits below the fold is a prime candidate to move up.
• below_fold_count / total_count — the raw counts behind the percentage (fixed-position elements are excluded, since they're always on screen).
• median_viewport_height — the typical fold line in CSS pixels, to recommend against.

Report it concretely, e.g. "the fold is ~600px for most visitors, yet 35% of clicks land below it, so users scroll before interacting — that content is a candidate for the first screen." Segment by device with viewport_width_min/viewport_width_max (desktop and mobile have very different folds) and read fold per band rather than blending them.

Need a distribution rather than a single percentage (e.g. clicks bucketed by how far below the fold)? Drop to SQL on the raw heatmaps table, which has y and viewport_height in the same scaled units — see the querying-posthog-data skill, models-heatmaps.

For each notable cluster, find what's actually there. Query autocapture on the same URL — either via the exploring-autocapture-events skill or directly:

SELECT properties.$el_text AS text, count() AS clicks
FROM events
WHERE event = '$autocapture'
  AND properties.$current_url = 'https://example.com/pricing'
  AND timestamp >= now() - INTERVAL 7 DAY
GROUP BY text
ORDER BY clicks DESC
LIMIT 25

elements_chain gives the selector/DOM path when you need to disambiguate two elements with the same text. Match autocapture's top elements to the heatmap's hot coordinates: clicks concentrated on something that is not a link or button (plain text, an image, a disabled control) is a classic "users expect this to be clickable" finding.

You can't see the page, but the user can. When a visual would help them follow your findings, create a saved heatmap so they can open the rendered page with the data overlaid in PostHog:

1. heatmaps-saved-create with the page url (type defaults to screenshot). This enqueues a headless render — it is asynchronous. Pass widths matching the viewport band you analyzed in Step 2.
2. Poll heatmaps-saved-get (by the returned short_id) until status is completed, then tell the user it's ready to view in PostHog.

This is for the human's benefit — your own reasoning still comes from the Step 2 data and the Step 3 autocapture identity, not from the picture.

For a surprising cluster, heatmaps-events returns the individual sessions behind specific points. Hand the session IDs to the investigating-replay skill to watch what people actually did.

Produce a short, concrete report:

• What the heatmap shows — top engaged elements, dead zones, scroll reach, and the above/below-the-fold click split (e.g. "viewport is ~600px for most visitors, yet 35% of clicks land below it").
• Problems, ranked by signal strength — rage-click clusters first, then clicks on non-interactive elements, then important CTAs sitting below the scroll cliff, then ignored primary actions.
• Recommendations tied to evidence — move/raise a CTA above the fold, make a clicked-but-dead element a real link, cut competing elements near a rage-click cluster, etc. Every recommendation should cite the signal it came from.