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 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.
  • --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:

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

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.

Summary