Scrapfly Screenshot API

The Screenshot API allows to capture screenshots of any web page or specific parts of the web page. This API comes with many convenience features like blocking bypass, viewport settings, full page capture auto scroll, banner blocking and much more!

If you need advanced scraping capabilities for screenshot capture like browser interaction, cookies, headers, etc. Use the full Web Scraping API to take screenshot instead. Screenshot API is a simplified version suited for more general screenshot capture.

This API is designed to be as simple as possible while maintaining the flexibility to capture any web page and is fully controlled through GET requests and URL parameters making it accessible in any environment.

Intro Video

On Steroids

Automatically unblock websites without extra configuration .
Directly receive the screenshot in jpg.
Gzip compression is available through the accept-encoding: gzip header.
Supports image conversion on the fly as webp, png, gif formats.

Quality of Life

All screenshot requests and metadata are automatically tracked on a Web Dashboard .
Multi project/scraper support through Project Management .
Ability to debug and replay scrape requests from the dashboard log page.
API Status page with a notification subscription.
Full API transparency through meta HTTP headers:
- X-Scrapfly-Api-Cost - API cost billed
- X-Scrapfly-Remaining-Api-Credit Remaining Api credit. If 0, billed in extra credits
- X-Scrapfly-Account-Concurrent-Usage You current concurrency usage of your account
- X-Scrapfly-Account-Remaining-Concurrent-Usage Maximum concurrency allowed by the account
- X-Scrapfly-Project-Concurrent-Usage Concurrency usage of the project
- X-Scrapfly-Project-Remaining-Concurrent-Usage If the concurrency limit is set on the project otherwise equal to the account concurrency
Concurrency is defined by your subscription

Billing

Scrapfly uses a credit system to bill Screenshot API requests.

Billing is reported in every scrape response through the X-Scrapfly-API-Cost header and the monitoring dashboard and can be controlled through Scrapfly budget settings.

For more see Screenshot Billing.

Errors

Scrapfly uses conventional HTTP response codes to indicate the success or failure of an API request.

Codes in the 2xx range indicate success.

Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, not permitted, max concurrency reached, etc.).

Codes in the 5xx range indicate an error with Scrapfly's servers.

HTTP 422 - Request Failed provide extra headers in order to help as much as possible:

X-Scrapfly-Reject-Code: Error Code
X-Scrapfly-Reject-Description: URL to the related documentation
X-Scrapfly-Reject-Retryable: Indicate if the screenshot is retryable

It is important to properly handle HTTP client errors in order to access the error headers and body. These details contain valuable information for troubleshooting, resolving the issue or reaching the support.

HTTP Status Code Summary

200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter or a bad value or a bad format.
401 - Unauthorized	No valid API key provided.
402 - Payment Required	A payment issue occur and need to be resolved
403 - Forbidden	The API key doesn't have permissions to perform the request.
422 - Request Failed	The parameters were valid but the request failed.
429 - Too Many Requests	All free quota used or max allowed concurrency or domain throttled
500, 502, 503 - Server Errors	Something went wrong on Scrapfly's end.
504 - Timeout	The screenshot have timeout
You can check out the full error list to learn more.

Specification

Scrapfly has loads of features and the best way to discover them is through the specification docs below.

The Following headers are available with the screenshot response:

X-Scrapfly-Upstream-Http-Code: The Status code the page
X-Scrapfly-Upstream-Url: The actual url of the screenshot after potential redirection

To start, you can try out the API directly in your terminal using your browser:

https://api.scrapfly.io/screenshot?url=https%3A%2F%2Fweb-scraping.dev%2Fproduct%2F1&key=

Or by using curl in your terminal:

curl -G \
--request "GET" \
--url "https://api.scrapfly.io/screenshot" \
--data-urlencode "key=" \
--data-urlencode "url=https://web-scraping.dev/product/1" -o screenshot.jpg

Command Explanation

curl -G:
- curl is a command-line tool for transferring data with URLs.
- -G specifies that the request should be a GET request and appends the data specified with --data-urlencode as query parameters.
--request "GET":
- --request "GET" explicitly sets the request method to GET. This is redundant since -G already indicates a GET request.
URL:
- The URL of the API endpoint being accessed: https://api.scrapfly.home/screenshot.
--data-urlencode "key=__API_KEY__":
- --data-urlencode encodes data as a URL parameter.
- "key=__API_KEY__" is the API key used for authentication.
--data-urlencode "url=https://web-scraping.dev/product/1":
- --data-urlencode encodes data as a URL parameter.
- "url=https://web-scraping.dev/product/1" is the URL of the web page to be screenshotted, URL-encoded.
--data-urlencode "options=load_images":
- --data-urlencode encodes data as a URL parameter.
- "options=load_images" specifies that images should be loaded in the screenshot.
-o screenshot.jpg:
- -o specifies the output file for the response.
- screenshot.jpg is the name of the file where the screenshot will be saved.

This will save the results to screenshot.jpg in the current directory:

open screenshot.jpg

Only documents of content-type text/* are eligible for screenshot, otherwise the error ERR::SCREENSHOT::INVALID_CONTENT_TYPE will be returned.

With that in mind, now you can explore the API specification to see all features that are available through URL parameters:

HTTP Parameter

Description

Example

url

required

Target url to scrape. Must be url encoded

url=https://httpbin.dev/anything?q=I%20want%20to%20Scrape%20this

key

required

API Key to authenticate the call

key=16eae084cff64841be193a95fc8fa67dso

format

default: jpg

Format of the screenshot image

format=jpg
format=png
format=webp
format=gif

capture

default: viewport

Area to capture in the screenshot, by default it captures the viewport. You can capture the full page, a specific element, or a vertical part of the page. It accepts XPATH or CSS Selector to target a specific element.

capture=viewport
capture=fullpage
capture=vertical
capture=#header
capture=/div/img[1]

resolution

default: 1920x1080

Screen resolution, width x height

resolution=1920x1080
resolution=320x860

country

popular

default: us

Proxy country location - If not set it chooses a random location available. A reference to a country must be ISO 3166 alpha-2 (2 letters).

country=us
country=us,ca,mx
country=us:1,ca:5,mx:3,-gb
country=-gb

timeout

default: 30000

Timeout is expressed in milliseconds. It represents the maximum time allowed to Scrapfly to try to take the screenshot. The minimum is 30000 (30s) and the maximum is 120000 (2 minutes).

timeout=30000

timeout=120000

rendering_wait

default: 1000

Delay in milliseconds to wait after the page was loaded.

rendering_wait=5000

wait_for_selector

popular

default: null

Await until given CSS Selector or XPATH is visible in the page

wait_for_selector=body
wait_for_selector=input[type="submit"]
wait_for_selector=//button[contains(text(),"Go")]

options

default: null

Screenshot options to customize the screenshot behavior. You can set the quality, format, and more. Here are the available flags:

dark_mode Enable dark mode display
block_banners Block cookies banners and overlay that cover the screen
print_media_format Render the page in the print mode

options=block_banners
options=block_banners,dark_mode

auto_scroll

default: false

Auto Scroll to the bottom of the page. It allows to trigger javascript rendering based on the user viewport intersection.

auto_scroll=true
auto_scroll=false

default: null

Script to execute in the page. Must be base64 encoded with url safe option.

If wait_for_selector is defined, the script is executed after and only if the selector is present.
If you need to wait or ensure you return data, use javascript await to prevent early return

js=ZG9jdW1lbnQuYm9keS5zdHlsZS5iYWNrZ3JvdW5kQ29sb3IgPSAncmVkJw

cache

default: false

Will store the screenshot for the given url. Greatly improve the performance of your application by caching the screenshot if you need to scrape the same page multiple times.

cache=true
cache=false

cache_ttl

default: 86400

Cache Time To Live in seconds. If you do a scrape after the TTL has expired, the target will be scraped and the cache refresh with the new data.

cache_ttl=60
cache_ttl=3600

cache_clear

default: false

Force to refresh the cache and ensure the scrape is performed to cache the new version

cache_clear=true
cache_clear=false

Related Errors

All related errors are listed below. You can see full description and example of error response on the Errors section.

ERR::SCREENSHOT::INVALID_CONTENT_TYPE - Only content type text/html is supported for screenshot
ERR::SCREENSHOT::UNABLE_TO_TAKE_SCREENSHOT - For some reason we were unable to take the screenshot

FAQ

Why are some images missing in my screenshot?

Some images can be loaded dynamically and render slowly. Try setting rendering_wait parameter to a few seconds (e.g. 3000) or wait for elements to load explicitly using wait_for_selector parameter.

Some images only load when scrolled into viewport so you can try increasing the viewport parameter to bigger values than the default 1920x1080. You can also use auto_scroll to have Scrapfly scroll to the very bottom of the page to force image loading.

Finally, some images can be blocked from loading by modals and banners. Use the block_banners flag in the options parameter to close any pop-ups, modals or banners i.e. options=block_banners.