Scrapfly Screenshot

Use the Scrapfly Screenshot API to capture high-quality screenshots of web pages with JavaScript rendering and anti-bot bypass.

When to use

Capturing full-page or viewport screenshots of websites
Taking screenshots of specific page elements via CSS selector/XPath
Rendering pages behind anti-bot protections for visual capture
Generating screenshots in different formats (JPG, PNG, WebP, GIF)
Testing pages at different screen resolutions

Setup

bash

pip install scrapfly-sdk

The API key must be provided via environment variable

SCRAPFLY_API_KEY

or passed directly to the client.

API Reference

Endpoint:

GET https://api.scrapfly.io/screenshot

ScrapflyClient

python

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

ScreenshotConfig Parameters

Parameter	Type	Default	Description
`url`	str	required	Target URL to screenshot
`format`	str or `Format`	`"jpg"`	Image format: `"jpg"` , `"png"` , `"webp"` , `"gif"` ( `Format` enum)
`capture`	str	`"viewport"`	Capture scope: `"viewport"` , `"fullpage"` , or a CSS selector/XPath
`resolution`	str	None	Screen dimensions, e.g. `"1920x1080"` , `"375x812"`
`country`	str	None	Proxy country (ISO 3166-1 alpha-2, e.g. `"us"` , `"de"` )
`timeout`	int	None	Total request timeout in milliseconds
`rendering_wait`	int	1000	Wait time in ms after page load before capture
`wait_for_selector`	str	None	Wait until this CSS/XPath selector is visible before capture
`options`	list[str] or list[ `Options` ]	None	Screenshot behavior flags, e.g. `"load_images"` , `"dark_mode"` , `"block_banners"` , `"print_media_format"` ( `Options` enum)
`auto_scroll`	bool	False	Scroll to bottom to trigger lazy-loading before capture
`js`	str	None	Raw JavaScript to execute before capture (SDK will base64‑encode; max 16KB)
`cache`	bool	None	Enable response caching for this screenshot request
`cache_ttl`	bool or int	None	Cache TTL (time-to-live); only effective when `cache=True`
`cache_clear`	bool	None	Clear existing cache entry for this URL when `cache=True`
`vision_deficiency`	str or `VisionDeficiency`	None	Simulate vision impairment for accessibility testing, e.g. `"deuteranopia"` , `"protanopia"` , `"achromatopsia"` ( `VisionDeficiency` enum)
`webhook`	str	None	Webhook name to receive async screenshot completion callbacks
`raise_on_upstream_error`	bool	True	Raise an exception if the upstream page returns an error status

Examples

Basic viewport screenshot

python

from scrapfly import ScrapflyClient, ScreenshotConfig
import os

client = ScrapflyClient(key=os.environ["SCRAPFLY_API_KEY"])

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
))

# Save the screenshot image
with open("screenshot.jpg", "wb") as f:
    f.write(result.image)

Full-page screenshot as PNG

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    format="png",
    capture="fullpage",
    auto_scroll=True,
))

with open("fullpage.png", "wb") as f:
    f.write(result.image)

Screenshot of a specific element

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/product/1",
    rendering_wait=5000,
    format="png",
    capture="div.features" # CSS selector
))

with open("element.png", "wb") as f:
    f.write(result.image)

Custom resolution (mobile)

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    resolution="375x812",  # iPhone viewport
))

with open("mobile.jpg", "wb") as f:
    f.write(result.image)

Screenshot with banner blocking and dark mode

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    options=["block_banners", "dark_mode"],
    rendering_wait=2000,
))

with open("clean_dark.jpg", "wb") as f:
    f.write(result.image)

Wait for dynamic content before capture

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    wait_for_selector="div.products",
    rendering_wait=3000,
))

with open("fully_loaded_screenshot.jpg", "wb") as f:
    f.write(result.image)

Screenshot with geo-targeting

python

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    country="de",
    resolution="1920x1080",
))

with open("german_version.jpg", "wb") as f:
    f.write(result.image)

Execute JavaScript before capture

Run custom JS before the screenshot (e.g. remove the navbar, cookie modal, or sidebar). Replace the selectors with ones that match your target page—inspect the page in DevTools to find them.

python

import base64

# Example: remove navbar (adjust selector for your page: nav, header, .navbar, etc.)

js_code = "var el = document.querySelector('.navbar-collapse'); if (el) el.remove();"
js_code = base64.urlsafe_b64encode(js_code.encode('utf-8')).decode('utf-8')

result = client.screenshot(ScreenshotConfig(
    url="https://web-scraping.dev/products",
    js=js_code, # remove the nav bar
    rendering_wait=1000,
))

with open("clean.jpg", "wb") as f:
    f.write(result.image)

Error Handling

python

from scrapfly.errors import ScrapflyError

try:
    result = client.screenshot(ScreenshotConfig(url="https://web-scraping.dev/products"))
    with open("screenshot.jpg", "wb") as f:
        f.write(result.image)
except ScrapflyError as e:
    print(f"Screenshot failed: {e.message}")

Important Notes

The
```
image
```
attribute on the response contains the raw binary image data
Use
```
format="png"
```
for pixel-perfect screenshots;
```
"jpg"
```
for smaller file sizes
```
auto_scroll=True
```
is recommended for
```
capture="fullpage"
```
to trigger lazy-loaded images
```
block_banners
```
removes cookie consent banners and overlay popups
```
rendering_wait
```
default is 1000ms; increase for JS-heavy pages
```
js
```
parameter content must be base64-encoded and under 16KB
Screenshots are stored by Scrapfly and retrievable via URL in the
```
X-Scrapfly-Screenshot-Url
```
response header

scrapfly-screenshot

NPX Install

Tags

SKILL.md Content

Scrapfly Screenshot

When to use

Setup

API Reference

ScrapflyClient

ScreenshotConfig Parameters

Examples

Basic viewport screenshot

Full-page screenshot as PNG

Screenshot of a specific element

Custom resolution (mobile)

Screenshot with banner blocking and dark mode

Wait for dynamic content before capture

Screenshot with geo-targeting

Execute JavaScript before capture

Error Handling

Important Notes