saved

Create a saved heatmap for a page URL. For type 'screenshot' (the default) this enqueues a headless render of the page at each target width; poll the saved heatmap or its content endpoint until status is 'completed'. Provide 'widths' to control which viewport widths are rendered.

post/api/projects/{project_id}/saved/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/saved/
  • Auth: HTTP bearer

Path parameters

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

namestring nullable

Human-readable label for the saved heatmap.

urlstring uri required

Exact page URL to render and overlay heatmap data on. Wildcards are not allowed.

data_urlstring

URL whose heatmap data is overlaid on the screenshot. Defaults to 'url' when omitted.

widthsinteger[]

Viewport widths (px, 100-3000) to render the heatmap screenshot at — one render per width. Defaults to [320, 375, 425, 768, 1024, 1440, 1920] when omitted. At most 16 widths.

type'screenshot' | 'iframe' | 'recording'
  • screenshot - Screenshot
  • iframe - Iframe
  • recording - Recording
deletedboolean

Set true to soft-delete the saved heatmap.

block_consent_modalsboolean

When true, ask the headless browser to dismiss cookie/consent banners before capturing the screenshot. Off by default: the blocker can stall the render on some sites and time out. Only applies to 'screenshot' heatmaps.

Response

idstring uuid required
short_idstring required

Short, URL-safe identifier used as the lookup key for saved-heatmap routes.

namestring nullable

Human-readable label for the saved heatmap.

urlstring uri required

The page URL this saved heatmap renders and overlays data on.

data_urlstring

URL whose heatmap data is overlaid on the screenshot (defaults to 'url').

target_widthsinteger[] required

Viewport widths (CSS pixels) the screenshot is rendered at.

type'screenshot' | 'iframe' | 'recording'
  • screenshot - Screenshot
  • iframe - Iframe
  • recording - Recording
source'server' | 'toolbar' required
  • server - Server
  • toolbar - Toolbar
status'processing' | 'completed' | 'failed' required
  • processing - Processing
  • completed - Completed
  • failed - Failed
has_contentboolean required

Whether at least one rendered image is ready to fetch.

deletedboolean

Soft-delete flag; deleted heatmaps are hidden from the list.

block_consent_modalsboolean

Whether the headless browser dismisses cookie/consent banners before capturing the screenshot. Only applies to 'screenshot' heatmaps.

created_atstring date-time required
updated_atstring date-time required
exceptionstring nullable required

Error detail when screenshot generation failed, otherwise null.

user_access_levelstring nullable required

The effective access level the user has for this object

Changes

No recorded changes to this operation across all 1 revision of this API.