ScreenshotRun plugs into Retool as a standard REST API Resource. You configure it once (base URL, Bearer token, done) and every app in your workspace can capture screenshots of any public or authenticated URL. No browser extensions, no html2canvas workarounds, no viewport-only hacks. Your Retool app sends a GET request with parameters, and the API returns a rendered screenshot or PDF. For teams building internal tools, a retool screenshot api setup like this takes about three minutes to wire up and covers everything from one-off captures to scheduled workflow automation.
Why Retool Needs an External Screenshot API
Retool ships with utils.downloadPage(), which sounds like it should solve the problem. In practice, it captures only the current Retool app viewport. It breaks on iframes. It chokes on custom components. And it cannot screenshot an external URL at all — it was never designed for that.
Retool's built-in PDF exporter has similar gaps. It supports markdown input only, strips CSS entirely, skips external images, and mangles any custom styling. If you need a pixel-accurate render of a web page saved as PDF, the exporter won't produce one.
Some teams try embedding html2canvas inside a custom component. That approach approximates the DOM rather than rendering it, so fonts render differently, cross-origin resources fail to load, complex layouts shift, and shadow DOM content disappears. Forum threads about these limitations go back years with no built-in solution on the roadmap.
An external screenshot API sidesteps all of this. A real Chromium browser loads the target page, waits for dynamic content, renders it fully, and returns the result as an image or PDF. Your retool screenshot api resource just calls that endpoint like any other REST integration.
Set Up ScreenshotRun as a REST API Resource
Open your Retool workspace, go to the Resources tab, and click "Create new." Select "REST API" as the type. Fill in these fields:
{
"name": "ScreenshotRun",
"base_url": "https://api.screenshotrun.com/v1/screenshots",
"authentication": "Bearer Token",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
That base URL covers the screenshots endpoint. Every query you build will append /capture plus whatever parameters the specific request needs. The Bearer token authenticates all requests automatically, so individual queries never need to handle auth themselves.
Save the resource. It now appears in every app's query dropdown across your workspace. Any team member building a Retool app can select "ScreenshotRun" as the resource and start capturing screenshots without touching the API key configuration again.
Capture a Screenshot from a Retool App
Create a new query in your Retool app. Select the ScreenshotRun resource you just created. Set the method to GET and the endpoint path to /capture. Add URL parameters to control what gets captured:
// Query: captureScreenshot
// Resource: ScreenshotRun
// Method: GET
// Endpoint: /capture
// URL Parameters:
url = {{ textInputUrl.value }}
format = png
width = 1280
height = 800
full_page = false
The url parameter binds to a TextInput component on your canvas, so users type a URL and trigger the capture. Wire a Button component's click handler to captureScreenshot.trigger(), and the query fires on demand.
ScreenshotRun returns the screenshot as a binary response by default. To display it directly, you have two paths: use the response URL that comes back in the headers, or request base64 output and embed it inline. Both approaches work well in Retool. The next section covers each pattern.
Display Screenshots in Retool Components
Retool's Image component accepts URLs, base64 strings, Retool Storage paths, or raw binary data. The simplest approach: set the Image component's source to the screenshot URL returned by the API.
// Image component → Image URL
{{ captureScreenshot.data.url }}
If you prefer inline display without a second network request, add response_type=base64 to your query parameters. The API returns a base64-encoded string that the Image component renders directly:
// Image component → Image URL (base64)
{{ "data:image/png;base64," + captureScreenshot.data.base64 }}
For applications that display multiple screenshots (a monitoring dashboard, for instance), use a Table component with an image column. Map each row's image field to the stored screenshot URL, and Retool renders thumbnails inline. The screenshot to base64 feature documentation covers the encoding options in more detail.
Binary responses also work if you want to let users download the screenshot. Set a Button component's click handler to utils.downloadFile(captureScreenshot.data, 'screenshot.png', 'image/png') and the browser saves it locally.
Generate PDFs in Retool
Switch the format parameter from png to pdf and the API returns a full PDF render of the target page. Unlike Retool's built-in PDF exporter (which only accepts markdown, ignores CSS, strips images), this produces an actual browser-rendered PDF with styles, fonts, layouts intact.
// Query: capturePdf
// Resource: ScreenshotRun
// Method: GET
// Endpoint: /capture
// URL Parameters:
url = {{ textInputUrl.value }}
format = pdf
full_page = true
pdf_page_format = A4
pdf_landscape = false
Client-facing reports, compliance archives, invoice snapshots. Any workflow that needs a PDF version of a live page works through this single parameter change. You can bind the format to a Select component so users toggle between PNG and PDF output without separate queries.
The website to PDF guide covers additional options like margin control, landscape orientation, header injection, and custom page sizes.
Automate Screenshots with Retool Workflows
Retool Workflows run outside of apps. They execute on a schedule or in response to webhooks, which makes them ideal for recurring screenshot tasks. A typical automated pipeline looks like this:
- Schedule trigger: set to run daily at 8 AM, weekly on Mondays, hourly during business hours, or whatever cadence your team needs.
- REST API block: point it at your ScreenshotRun resource. Pass the target URL, format, full_page parameters. The block returns the screenshot binary or URL.
- Storage block: upload the result to S3, Google Cloud Storage, Retool Database, or write a record to your own database with the screenshot URL and timestamp.
- Notification block: send the screenshot as a Slack message attachment or email it to stakeholders.
// Retool Workflow: Daily Dashboard Capture
// Block 1: Schedule Trigger → Every day at 08:00 UTC
// Block 2: REST API (ScreenshotRun)
// Method: GET
// URL: https://api.screenshotrun.com/v1/screenshots/capture
// Headers: Authorization: Bearer YOUR_API_KEY
// Params:
// url = https://your-app.internal.com/dashboard
// format = png
// width = 1920
// height = 1080
// full_page = true
// block_ads = true
// Block 3: S3 Upload
// Bucket: your-screenshots-bucket
// Key: dashboards/{{ new Date().toISOString().slice(0,10) }}.png
// Body: {{ block2.data }}
// Block 4: Slack Notification
// Channel: #reports
// Message: "Dashboard snapshot captured for {{ new Date().toISOString().slice(0,10) }}"
For teams already storing screenshots in S3, the Amazon S3 integration guide explains how to pair ScreenshotRun output with bucket storage. The scheduled screenshots page covers cron-like patterns in more depth.
JavaScript Query for Advanced Logic
When you need conditional logic, chained operations, or error handling beyond what a standard REST query provides, use a JavaScript Query. Retool's JS queries run server-side and support fetch(), so you can call the ScreenshotRun API directly and process the response before passing it to components.
// JavaScript Query: advancedCapture
const apiKey = "YOUR_API_KEY";
const targetUrl = textInputUrl.value;
const selectedFormat = selectFormat.value || "png";
const params = new URLSearchParams({
url: targetUrl,
format: selectedFormat,
width: "1280",
height: "800",
full_page: checkboxFullPage.value ? "true" : "false",
block_ads: "true",
dark_mode: toggleDarkMode.value ? "true" : "false"
});
const endpoint = `https://api.screenshotrun.com/v1/screenshots/capture?${params}`;
try {
const response = await fetch(endpoint, {
method: "GET",
headers: {
"Authorization": `Bearer ${apiKey}`
}
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.message || "Capture failed");
}
const result = await response.json();
// Store the screenshot record in your database
await queryInsertScreenshot.trigger({
additionalScope: {
screenshotUrl: result.url,
capturedAt: new Date().toISOString(),
sourceUrl: targetUrl
}
});
// Notify via Slack if checkbox is checked
if (checkboxNotify.value) {
await querySlackNotify.trigger({
additionalScope: {
message: `Screenshot captured: ${result.url}`
}
});
}
return result;
} catch (err) {
utils.showNotification({
title: "Screenshot Error",
description: err.message,
notificationType: "error"
});
return null;
}
This pattern gives you full control. Bind UI toggles to parameters like dark mode or full page. Chain the capture with a database insert and a Slack notification. Handle errors with Retool's built-in notification system. JavaScript Queries turn a single API call into a multi-step workflow embedded right in the app.
Parameters for Retool Screenshot Queries
Every parameter goes into the URL Parameters section of your Retool query. These are the ones most relevant for internal tool builders:
| Parameter | Value | What It Does |
|---|---|---|
url |
Any public URL | The page to capture. Bind to a TextInput for user-driven captures. |
format |
png, jpeg, webp, pdf | Output format. Use pdf for document archival, webp for smaller file sizes. |
width |
Integer (px) | Viewport width. 1280 is standard desktop, 390 for mobile. |
height |
Integer (px) | Viewport height. Ignored when full_page is true. |
full_page |
true / false | Capture the entire scrollable page. See full page screenshots. |
block_ads |
true / false | Remove ads before capture. Cleaner output for reports. See ad blocking. |
dark_mode |
true / false | Force dark mode rendering. See dark mode screenshots. |
selector |
CSS selector | Capture a specific element only. Useful for isolating charts or widgets. |
delay |
Integer (ms) | Wait after page load before capturing. Helps with pages that animate in content. |
device |
desktop, mobile, tablet | Simulates a device viewport with appropriate user agent and screen size. |
Bind any of these to Retool components (dropdowns, checkboxes, number inputs) and your app becomes a configurable screenshot tool that non-technical team members can operate without touching the query setup.
What Teams Build with This Integration
A retool screenshot api integration opens up workflows that Retool alone cannot handle. These are the patterns we see most often.
Dashboard report snapshots. Operations teams capture internal dashboards every morning and archive the images. A Retool Workflow fires at 8 AM, screenshots the Metabase or Grafana dashboard, uploads to S3, and posts the image to Slack. Stakeholders see the daily snapshot without logging into the analytics tool. The dashboard screenshots page walks through this pattern end to end.
Compliance archival. Regulated industries need timestamped proof of what a web page displayed on a specific date. A Retool app lets compliance officers paste a URL, capture a full-page screenshot with metadata, and store it alongside case records in the database. Every capture gets a timestamp and an immutable record. See website compliance monitoring for the regulatory side of this workflow.
Client-facing reports. Agencies and SaaS companies generate visual reports for clients. Instead of manually screenshotting competitor sites, landing pages, ad creatives, or social media profiles, a Retool app captures them in bulk. Bind a list of URLs to a loop, capture each one, assemble the results into a PDF or image grid, and share the report from a single internal tool.
Website monitoring dashboards. DevOps teams build Retool dashboards that capture screenshots of production pages at regular intervals. When something looks off — a broken layout, a missing image, a rogue deployment — the visual history makes it obvious. Pair this with the webhook feature to get notified the moment a capture completes, rather than polling for results.
E-commerce preview tools. Product teams managing hundreds of listings need to verify how pages render across devices. A Retool app with a retool screenshot api query captures the same product URL at desktop, mobile, tablet, and retina viewports side by side. QA reviewers spot layout issues, missing images, or price display bugs without opening each page manually in different browsers.
ScreenshotRun fits Retool's philosophy of building fast with reliable external services. One REST API Resource replaces browser extensions, fragile html2canvas hacks, and the broken utils.downloadPage() path. You get a managed Chromium fleet behind a single endpoint, 200 free screenshots per month on the starter plan, and response times under two seconds for most pages. The API handles ad blocking, cookie consent removal, full-page scrolling, geo-targeted captures, and PDF generation out of the box. Your Retool app stays focused on the workflow while ScreenshotRun handles the rendering.
FAQ#
Create a REST API Resource in your Retool workspace with the base URL https://api.screenshotrun.com/v1/screenshots and an Authorization: Bearer header containing your API key. Then create queries in any app using that resource, passing url, format, and other parameters to the /capture endpoint.
Not with built-in tools. Retool's utils.downloadPage() only captures the current app viewport and cannot render external URLs. An external screenshot API like ScreenshotRun fills this gap by capturing any public URL through a simple REST query.
Set the Image component source to the URL returned by the API query, like {{ captureScreenshot.data.url }}. For inline display without a second network request, add response_type=base64 to your query parameters and use a data URI prefix: data:image/png;base64, followed by the response string.
Yes. Set the format parameter to pdf in your ScreenshotRun query. The API renders the page in a real browser and returns a PDF with full CSS, fonts, and images intact. This produces better results than Retool's built-in PDF exporter, which only accepts markdown input.
Create a Retool Workflow with a Schedule trigger set to your desired frequency. Add a REST API block pointing to your ScreenshotRun resource with the capture parameters. Follow it with a Storage block to save the result to S3 or a database, and optionally a notification block to send via Slack or email.
Yes. Use fetch() inside a JavaScript Query to call the API directly. This gives you full control over conditional logic, error handling, and chaining multiple operations like capturing a screenshot, storing it in a database, and sending a notification in sequence.