:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Toolbar plan entitlements
GET /api/user/toolbar_entitlements/ requires a logged-in session and access to the toolbar for the current project. It returns an entitlements map of feature names to booleans, based on the current organization’s available features. ToolbarEntitlementsSerializer defines its OpenAPI response schema.
Gated toolbar tools are a Cloud plan entitlement. On a self-hosted deployment the endpoint reports every gated feature as entitled, so a rollout can never take a toolbar tool away from a self-hosted user, licensed or not. Legacy self-hosted license tiers therefore do not list these features.
When the toolbar-paid-heatmaps rollout flag is enabled, toolbar heatmaps require toolbar_heatmaps: true. Loading, failed requests, and missing entitlements do not grant access. The menu shows a loading state while checking access and offers a retry when access cannot be determined. A failed request is logged under the entitlements context and reported in the toolbar api request telemetry, so the rollout can be watched without waiting for a user report. The request gives up after five seconds, so a stalled one reaches that retry rather than spinning for the rest of the page session. Only an explicit false shows the plan upgrade prompt.
The toolbar button follows the same rule: it carries the lock badge only for an explicit false, and while the check is pending or failed its tooltip says that instead of asking for a subscription.
That prompt also offers a recheck, so a user who upgrades in the billing tab unlocks the tool without reloading the page they are working on.
Opening the heatmap menu while access is loading does not enable heatmaps. A confirmed entitlement enables the open menu; refreshing or losing that entitlement disables heatmaps. A rollout flag that arrives after the menu opened reconciles the open heatmap the same way, so the page overlays cannot stay painted under the plan panel. When the rollout flag is disabled, the toolbar retains its existing behavior.
This is a toolbar UI gate. The rollout flag does not add entitlement enforcement to the heatmap data endpoints.
The HeatmapEntitlementsLoading Storybook story keeps the entitlement request pending to cover the loading state. Its screenshot test waits for “Checking plan access…” to appear and sets waitForLoadersToDisappear: false so the visible spinner does not time out the test.
Saved heatmap data URLs
Capture requests reject malformed data URLs, using the same URL validation as other saved heatmap writes. Wildcards in the URL path are supported.
Saving a heatmap from the toolbar keeps the captured page URL separate from the heatmap data URL. The saved data URL preserves the toolbar's selected URL pattern, including wildcards, for both responsive captures and the single-width fallback. Capture requests without a data URL keep using the exact page URL.
A heatmap editor with resource-level access can change the data URL of a toolbar capture in the page settings without replacing its screenshot. Changing the captured page or its rendering settings still requires a new capture from the toolbar. Object-level editor access alone does not allow changing either URL.
Saving again retries all configured page widths and creates a new heatmap. It does not add missing widths to an existing heatmap.
Screenshot capture
Saving a heatmap uses the browser's current page to capture screenshots at several widths. Screenshots are JPEG images on a white background. Web fonts the page uses are embedded at every width. Canvases keep their size at every width. Images and video posters that cannot load, cannot decode, or answer with an error status such as 403 leave blank areas without changing the layout. Unreadable canvases and video frames also leave their original space in the screenshot. Image, font, and stylesheet fetches share a 15-second deadline for each capture. Stylesheets that miss this deadline are skipped so later capture widths can continue. This deadline does not bound the whole rendering process. An image that is still loading when a width finishes waiting stays blank at that width and every later width, so one slow host delays a save once instead of at every width. Capturing never changes the page's own stylesheets. Failed resource fetches are not cached, so later widths and save attempts can load a recovered resource. Successfully loaded resources remain cached.