How do I delete an already taken heatmap snapshot?

Cloud On-Premise

Matomo captures a snapshot of the tracked page to display your heatmap data. If the snapshot is outdated or does not represent the page correctly, you can delete it and take a new one.

A new snapshot can be captured automatically or manually while the heatmap is still recording.

  1. Open the active heatmap in Matomo.
  2. Click on Heatmap Settings and select Delete and retake the snapshot.
    delete and retake heatmap snapshot
  3. Choose one of the following methods:
    • Delete and retake manually: Matomo deletes the current snapshot. You can then open the target page and manually capture its current state.
    • Delete and retake automatically: Matomo deletes the current snapshot. A new snapshot is captured when the first recorded visitor views the target page.

Manual capture is recommended when your page loads elements dynamically. It gives you control over when Matomo captures the page after its content has fully loaded.

If you delete an existing snapshot, the message depends on the selected capture method.

  • For automatic capture, you will see the message: “A new snapshot will be taken when a visitor views the target page.”
  • For manual capture, Matomo displays instructions on-screen for opening the tracked page and running the JavaScript capture command. Read how to capture the snapshot manually.

After the heatmap has finished recording

Once a heatmap has finished recording, Matomo cannot capture another snapshot for it. You can still delete the existing snapshot. However, the options to retake it automatically or manually are no longer available.

Note: If you delete the snapshot after recording has finished, it is no longer possible to add a snapshot to this heatmap. Only delete a snapshot from a completed Heatmap if you no longer need it. You cannot restore or replace the snapshot after a heatmap has finished.

To receive email notifications when a heatmap has finished recording, enable the notify option in General settings. See Notify me when a heatmap completes.

API method

Use the API method HeatmapSessionRecording.deleteHeatmapScreenshot with your Matomo site ID (idSite) where the heatmap is saved and the ID of the heatmap you want to delete (idSiteHsr). Include a valid Matomo authentication token with permission to delete the heatmap. For example:

?module=API&method=HeatmapSessionRecording.deleteHeatmapScreenshot&idSite=1&idSiteHsr=5&format=json&token_auth=your_token

Console command

For Matomo On-Premise, you can also use the console command with your Matomo site ID (idSite) and the heatmap ID (idHeatmap). For example:

./console heatmapsessionrecording:remove-heatmap-screenshot --idsite={idsite} --idheatmap={idHeatmap}

The console command can also be used to retake the screenshot of an already finished heatmap. In this case, the heatmap will be temporarily restarted and up to 50 new samples will be taken so a screenshot can be taken. Then the heatmap will end automatically.

Previous FAQ: How do I stop recording further heatmap or session recording activities?