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.
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:
- Go to Credentials → Add credential and choose Header Auth.
- Name:
x-api-key - Value: your Screenshotly API key
- 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) andheight(240–3840), ordevice:desktop,laptop,tabletormobile. There is noviewportobject. fullPage: truecaptures the whole document. Without it you get the visible viewport only.format:png,jpegorwebpon every plan.pdfandhtmlneed Basic.webmneeds Scale.- Waiting:
waitForNetworkIdle: true,waitForSelector: "#app"ordelay(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),hideSelectorsandmockupneed 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
dataand a key such ascaptures/{{ $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.
Get a link instead of a file
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-Afterheader. The JSONmessagesays 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
400and403, 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:
About the Author

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.