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
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 using your browser:
Or by using curl in your terminal:
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
.
- The URL of the API endpoint being accessed:
-
--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:
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:
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
.