Skip to main content
Figranium automatically captures visual evidence and intercepted files from your automation runs. This is crucial for debugging, auditing, and ensuring quality.

Screenshots

View full-page or viewport captures saved as PNG files.

Video Recordings

Watch full-session WebM recordings of Agent task runs.

File Downloads

Access intercepted files from browser download events.

Cookie Persistence

Manage persistent browser profiles and session state.

​
Screenshots

By default, every successful Agent task captures a final screenshot of the page.
  • Format: PNG
  • Location: public/captures/<run_id>_screenshot.png
  • Accessibility: Open the run in Executions to see its screenshot in the detail view.
Scrape mode does not produce screenshots. Scrape mode runs an HTTP fetch through got-scraping and parses the response with Cheerio — no browser is launched, so there is no page to photograph. Opening a scrape execution in the editor shows a “Scrape mode does not support screenshots” placeholder in the Screenshot panel where the image would otherwise render. If you need visual evidence of the page, use Agent mode.

​
Custom Screenshots

You can trigger additional screenshots during an agent task using the screenshot action block.
  • Filename: <run_id>_<timestamp>_<custom_suffix>.png
  • Full Page: (Optional) Capture the entire scrollable area.

​
Video Recordings

Figranium can record full session videos (WebM format) for Agent tasks.
  • Enable: Set disableRecording to false in the task editor.
  • Location: public/captures/<run_id>.webm
  • Playback: Open the run in Executions and click View All Captures in the detail view.
Recording consumes more disk space and CPU. Disable it for high-volume scraping. Scrape mode never records video for the same reason it doesn’t take screenshots — it doesn’t launch a browser.

​
File Downloads

Figranium automatically intercepts files downloaded during an automation run. For more details on how to manage and access these files, see the File Downloads documentation. Figranium stores cookies and browser session state in persistent profile directories on disk — one per execution mode:
  • data/browser-profile — agent mode
  • data/browser-profile-scrape — scrape mode
  • data/browser-profile-headful — headful/VNC mode
Each mode has its own isolated profile. Cookies from a headful login are bridged to agent and scrape runs automatically via data/headful-storage-state.json — headful writes this file every 30 seconds and on session close; agent and scrape inject it at startup (skipped for stateless runs).
  • Persistence: Cookies persist across browser restarts and task executions (unless statelessExecution is enabled).
  • Clear all: Clear all workspace data under Maintenance in Settings > Advanced removes browser profiles along with other workspace data.

​
Upgrading from v0.9.6 or Earlier

If you are upgrading from a version that used storage_state.json, Figranium will automatically migrate your existing cookies into all three profile directories on first startup. The storage_state.json file is then deleted. No manual action is required.

​
Stateless Execution

If you enable statelessExecution in a task, it will launch a fully ephemeral in-memory browser session (no cookies, no disk profile written) and discard any changes upon completion. This is ideal for testing login flows or anonymous scraping.

​
Storage Management

​
Automatic Retention

Starting in v0.19, Figranium deletes old captures and execution history automatically. The default retention period is 7 days. To change it, open Settings > Advanced, pick a period under Data retention (1, 3, 7, 14, 30, 90, or 365 days, or Never), and click Save retention.
  • Cleanup runs at startup and then every hour.
  • It removes capture files in public/captures, src/public/captures, and data/recordings that are older than the retention period, plus matching execution records. Both JSON and PostgreSQL storage are supported.
  • Shortening the period asks for confirmation and runs cleanup immediately.
  • The panel shows when cleanup last ran and how many captures and executions it removed. Open execution lists update live after pruning.
Retention cleanup permanently deletes data. Choose Never if you manage cleanup yourself.
You can also read and set retention through GET and POST /api/settings/system.

​
Exporting data

Export a backup of your workspace data, or move it to another Figranium instance, as a ZIP file.
  1. Open Settings > Advanced and find Export data.
  2. Select the categories to include. All five are selected by default.
  3. Click Export selected. Your browser downloads figranium-export-YYYY-MM-DD.zip.
Every archive also includes manifest.json, which records the export time and the selected categories:
Tasks, executions, and API keys are exported from the active storage backend, so export works with both JSON files and PostgreSQL.
API keys and cookies are exported in readable form. Anyone with the archive can use them to call your API or reuse your logged-in sessions. Leave them unselected unless you need them, and store the file securely.
You can also export through POST /api/settings/export.

​
Importing data

Restore selected categories from a Figranium export ZIP in Settings > Advanced > Import data. Choose the archive, select the categories to restore, and click Import selected. Imported categories replace their matching workspace data. Categories you leave unselected are not changed. Use the import flow when moving selected Tasks, Executions, Captures, API Keys, or Cookies between instances. Treat archives as sensitive because API keys and cookies are readable inside the ZIP.

​
File Cleanup

Screenshots, videos, and downloaded files accumulate in public/captures. Video recordings are stored separately in data/recordings. You can delete or download them:
Agent runs write captures to src/public/captures, while scrape runs write to public/captures. Figranium serves and reads from both paths, so captures always surface in a run’s execution detail regardless of which mode produced them. If you run Figranium in Docker, mount the same host directory to both /app/public/captures and /app/src/public/captures so no captures are lost. See Installation with Docker Compose for the recommended volume configuration.
  1. Download: Open a run in Executions, click View All Captures, then click the download icon on any capture card to save the file to your device.
  2. Single delete: Send a request to DELETE /api/data/captures/:name.
  3. Clear all: Click Clear captures under Maintenance in Settings > Advanced to delete every screenshot and recording at once.
When you clear captures, both screenshots in public/captures and video recordings in data/recordings are deleted.

​
Execution Logs

Execution metadata is stored in data/executions.json. Browser session profiles are stored separately in data/browser-profile* directories and are not affected by execution log rotation. This file grows over time. Figranium keeps at most 500 execution records (MAX_EXECUTIONS in server/constants.js) and also prunes records older than the retention period. Each stored execution record is capped at 256 KB (override with MAX_PERSISTED_EXECUTION_BYTES). When a result is larger, Figranium keeps the run in history but replaces the HTML and data with a truncation notice, keeps the first 20 log lines, and marks the result truncated: true. The full result is still returned to the caller that ran the task. This keeps an oversized payload from destabilizing the server. Starting in v0.20, Figranium also stores the complete result separately and marks the trimmed record hasFullResult: true. To view it, open the run in Executions and click Load full data, or call GET /api/executions/{id}/result. The endpoint returns { "result": ... } with the complete stored result, or 404 with FULL_RESULT_NOT_AVAILABLE if no full result was stored. Full results are deleted together with their execution records by retention. To clear history manually, use Clear execution history under Maintenance in Settings > Advanced.
Downloaded files stored in Cabinets are not affected by retention. Monitor disk usage on your host if you run high-volume tasks.