Guide

n8n Screenshot Integration: Self-Hosted Automation for Screenshots

An importable n8n workflow that captures a list of URLs with the Screenshotly API and saves each image as a file, tested on n8n 2.47.

Asad AliJanuary 6, 20269 min read

n8n is a workflow automation tool you can self-host or use as n8n Cloud. It has no Screenshotly node, and it doesn't need one: the built-in HTTP Request node can call the API, receive the image as a file and hand it to any storage node.

This guide gives you a workflow you can import, explains each setting, and covers the limits that matter in production: request rate, quota, timeouts and errors.

Tested with: n8n 2.47.5 (Docker image docker.n8n.io/n8nio/n8n), against an offline mock of the Screenshotly API that uses the production request schema and plan rules. Field labels can move between n8n versions, so if something looks different, check the HTTP Request node docs.

What you need

  • n8n, self-hosted or Cloud. For self-hosting, follow n8n's own Docker installation guide.
  • A Screenshotly API key. The free plan includes 100 captures in total at up to 5 requests per minute, with PNG, JPEG and WebP output.

Step 1: Create the credential

Store the key once, as an n8n credential, instead of pasting it into nodes:

  1. Go to Credentials → Add credential and choose Header Auth.
  2. Name: x-api-key
  3. Value: your Screenshotly API key
  4. Save it as Screenshotly API key.

Authorization with the value Bearer YOUR_KEY also works, but x-api-key keeps the value simple.

Step 2: Import the workflow

Save this JSON as screenshotly-capture.json, then in n8n open a new workflow and use Import from File from the workflow menu. After importing, open the Screenshotly capture node and select your credential (the ID in the file is a placeholder).

{
  "name": "Screenshotly: capture URLs to files",
  "nodes": [
    {
      "parameters": {},
      "id": "a1",
      "name": "Manual Trigger",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [
        0,
        0
      ]
    },
    {
      "parameters": {
        "jsCode": "return [\n  { json: { url: 'https://example.com', name: 'example-home' } },\n  { json: { url: 'https://example.com/pricing', name: 'example-pricing' } },\n];"
      },
      "id": "a2",
      "name": "URLs to capture",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        220,
        0
      ]
    },
    {
      "parameters": {
        "method": "POST",
        "url": "https://screenshotly.app/api/screenshot",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "={{ JSON.stringify({ url: $json.url, width: 1280, height: 800, fullPage: true, format: 'png' }) }}",
        "options": {
          "batching": {
            "batch": {
              "batchSize": 1,
              "batchInterval": 13000
            }
          },
          "response": {
            "response": {
              "responseFormat": "file",
              "outputPropertyName": "data"
            }
          },
          "timeout": 60000
        }
      },
      "id": "a3",
      "name": "Screenshotly capture",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        440,
        0
      ],
      "credentials": {
        "httpHeaderAuth": {
          "id": "REPLACE_WITH_YOUR_CREDENTIAL",
          "name": "Screenshotly API key"
        }
      },
      "retryOnFail": true,
      "maxTries": 3,
      "waitBetweenTries": 5000
    },
    {
      "parameters": {
        "operation": "write",
        "fileName": "=/home/node/.n8n-files/{{ $('URLs to capture').item.json.name }}-{{ $now.toFormat('yyyy-MM-dd') }}.png",
        "dataPropertyName": "data",
        "options": {}
      },
      "id": "a4",
      "name": "Write file",
      "type": "n8n-nodes-base.readWriteFile",
      "typeVersion": 1,
      "position": [
        660,
        0
      ]
    }
  ],
  "connections": {
    "Manual Trigger": {
      "main": [
        [
          {
            "node": "URLs to capture",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "URLs to capture": {
      "main": [
        [
          {
            "node": "Screenshotly capture",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Screenshotly capture": {
      "main": [
        [
          {
            "node": "Write file",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "settings": {
    "executionOrder": "v1"
  }
}

The workflow has four nodes:

Manual Trigger → URLs to capture (Code) → Screenshotly capture (HTTP Request) → Write file (Read/Write Files from Disk)

Run it with Execute workflow. Each URL produces one PNG file named after the item and the date, for example example-home-2026-11-13.png.

How the HTTP Request node is configured

Setting Value Why
Method POST The capture endpoint only accepts POST.
URL https://screenshotly.app/api/screenshot The synchronous capture endpoint.
Authentication Generic credential type → Header Auth Sends x-api-key from the credential.
Send Body On, Body Content Type JSON, Using JSON The API expects a JSON body.
JSON {{ JSON.stringify({ url: $json.url, width: 1280, height: 800, fullPage: true, format: 'png' }) }} Builds a valid body from each incoming item.
Options → Response → Response Format File, output field data The response body is the image.
Options → Batching 1 item per batch, 13,000 ms interval Stays under the free plan's 5 requests per minute.
Options → Timeout 60,000 ms A capture can take up to about 30 seconds.
Settings → Retry On Fail On, 3 tries, 5,000 ms apart Covers temporary failures. See the caveat below.

The request body

Use only fields the API knows. It rejects unknown fields with a 400 Invalid request data, which is the most common mistake when copying older examples:

  • Viewport: top-level width (320–3840) and height (240–3840), or device: desktop, laptop, tablet or mobile. There is no viewport object.
  • fullPage: true captures the whole document. Without it you get the visible viewport only.
  • format: png, jpeg or webp on every plan. pdf and html need Basic. webm needs Scale.
  • Waiting: waitForNetworkIdle: true, waitForSelector: "#app" or delay (up to 10,000 ms) for pages that render late.
  • Cleanup: blockAds: true (every plan) blocks known ad requests and hides common ad and cookie-banner elements. AI element removal (aiRemoval), hideSelectors and mockup need Growth.

The full list is in the API reference.

Adapting the workflow

Run it on a schedule

Replace Manual Trigger with a Schedule Trigger (for example, every day at 09:00). Nothing else changes.

Read URLs from a sheet or database

Replace the URLs to capture Code node with Google Sheets, Airtable, Postgres or any node that outputs one item per URL with a url field. If your field has another name, change $json.url in the JSON body.

Save somewhere other than disk

The Write file node writes to the n8n server's disk, which suits self-hosted setups. Recent n8n versions only allow file access inside a configured folder; the example uses /home/node/.n8n-files, which must exist. For anything shared, swap it for a storage node and point it at the binary field data:

  • Google Drive → Upload file: set Input Data Field Name to data.
  • AWS S3 → Upload a file: use the binary field data and a key such as captures/{{ $now.toFormat('yyyy-MM-dd') }}/{{ $json.name }}.png.
  • Send Email or Slack: attach the binary field data.

Capture signed-in pages

On the Basic plan and above, add cookies (or headers) to the JSON body:

{{ JSON.stringify({
  url: $json.url,
  width: 1440,
  height: 900,
  cookies: [{ name: 'session', value: $json.session, domain: 'app.example.com' }]
}) }}

The API can't log in for you. The session value must come from a system that already has one, and it should be stored as securely as the API key.

On the Basic plan and above, add storage: { enabled: true } to the body and set Response Format back to JSON. The API then returns:

{ "success": true, "url": "https://screenshotly.app/api/assets/…?expires=…&signature=…", "format": "png", "size": 48213, "duration": 2140 }

The signed url works for 24 hours, and the file itself is kept for your account's retention period (7 days by default, 1–30 days). Copy the file to your own storage if you need it longer.

Rate limits, quota and retries

  • Request rate: 5 per minute on Free, 40 on Basic, 80 on Growth and 200 on Scale. Set the Batching interval to match: 13,000 ms is safe on Free, and paid plans can go lower.
  • Quota: Free includes 100 captures in total. Paid plans reset monthly (2,500 Basic, 12,000 Growth, 50,000 Scale). Failed captures don't count.
  • 429 responses come with a Retry-After header. The JSON message says whether you hit the per-minute rate or used up the quota. Retrying helps with the first, not the second.
  • Retry On Fail retries every error, including 400 and 403, which will never succeed. Keep the number of tries low, or turn it off and handle failures with the error output below.

Handling failures

n8n reports an HTTP error with its own generic message and puts the API's error field in the description. For example, a PDF request on the free plan shows Forbidden - perhaps check your credentials? with the description Plan upgrade required. Read the description first:

Status Screenshotly error What it means
400 Invalid request data, Invalid JSON, Unsafe URL Unknown field, value out of range, malformed body, or a private address
401 Authentication failed Missing or wrong x-api-key
403 Plan upgrade required The option needs a higher plan; minimumPlan says which
429 Rate limit exceeded Per-minute rate or quota reached
500 Screenshot generation failed The page couldn't be captured, for example it blocked automation or didn't load within 30 seconds

To keep a batch running when one URL fails, open the HTTP Request node's Settings and set On Error to Continue (using error output). Then connect the error output to a Slack, email or database node that records the URL and message. For alerts across all workflows, create an error workflow that starts with an Error Trigger and select it under the workflow's Settings → Error workflow.

Responding to a webhook with the image

To let another system request a capture, start with a Webhook node set to respond Using 'Respond to Webhook' node, run the same HTTP Request node, and finish with Respond to Webhook set to respond with Binary File from the data field. Protect the webhook with authentication. Anyone who can call it spends your capture quota.

Self-hosting notes

  • Follow n8n's current Docker Compose instructions for production. Persist /home/node/.n8n, or you lose credentials and workflows on restart.
  • The old N8N_BASIC_AUTH_* variables were removed in n8n 1.0. n8n now has built-in user accounts.
  • Keep the Screenshotly key in an n8n credential rather than an environment variable, so it is encrypted at rest and never shown in node parameters.
  • Screenshotly is a hosted API: each capture is rendered on Screenshotly's servers, not inside your n8n instance. Self-hosting n8n keeps your workflow data on your infrastructure, but the URLs you capture (and any cookies you send) still go to Screenshotly.

What this workflow doesn't do

  • Compare images. n8n has no built-in image diff. Use a Code node with a library, or an external service, if you need change detection. Comparing file sizes is not a reliable signal.
  • Interact with pages. The API loads one URL and captures it. Multi-step flows such as logging in or filling forms need a browser automation tool.

Ready to build it?

Create a free API key →. It includes 100 captures to test the workflow.

See also:

n8n
no-code
automation
self-hosted
integrations

About the Author

Asad Ali

Asad Ali

CTO at ZTABS and the developer behind Screenshotly. Writes about screenshot automation, API design, and building reliable SaaS backends with Next.js, Node.js, and TypeScript.

Credentials: CTO at ZTABS, full-stack developer, builder and maintainer of Screenshotly and its official JavaScript and Python clients

Frequently Asked Questions

Is there a Screenshotly node for n8n?

No. You call the API with n8n's built-in HTTP Request node, which works on self-hosted n8n and n8n Cloud. The workflow in this guide is ready to import.

How do I handle the binary image response in the HTTP Request node?

Under Options, add Response and set Response Format to File. n8n then stores the image as binary data in the field you name (this guide uses data), and later nodes such as Read/Write Files from Disk, Google Drive or S3 can read it from that field.

Why does n8n say 'Forbidden - perhaps check your credentials?'

n8n shows that text for any 403. From Screenshotly, a 403 usually means the request used an option your plan doesn't include, such as PDF on the free plan. Check the error description: 'Plan upgrade required' means the key is fine and the option needs a higher plan.

Ready to capture your first screenshot?

Get started with 100 free screenshots. No credit card required.

Related Articles