Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zenrows.com/llms.txt

Use this file to discover all available pages before exploring further.

The screenshot=true parameter tells ZenRows to capture a screenshot of the target page and return it as a PNG image. You get a pixel-accurate visual snapshot of the page as it appears in a browser, including styles, fonts, and JavaScript-rendered content. This is useful for visual monitoring, page archiving, UI testing, or any workflow that needs a rendered image of a page rather than its raw content.
Screenshot parameters cannot be combined with the outputs parameter. Use one or the other depending on whether you need a visual capture or targeted data extraction.

​
How it works

Screenshot generation always requires a full browser render. You must include js_render=true in every screenshot request. ZenRows renders the page in a headless browser and captures the result as an image before returning it as binary content. By default, the screenshot captures only the above-the-fold visible area of the page. You can expand this to the full page or narrow it to a specific element using the additional parameters described below.
Find more details on our JS Rendering Documentation.

​
Basic usage

Add screenshot=true and js_render=true to your request parameters: 
import requests

url = "https://www.scrapingcourse.com/ecommerce/"
apikey = "YOUR_ZENROWS_API_KEY"

params = {
    "url": url,
    "apikey": apikey,
    "js_render": "true",
    "screenshot": "true",
}

response = requests.get("https://api.zenrows.com/v1/", params=params)

with open("screenshot.png", "wb") as file:
    file.write(response.content)

print("Screenshot saved to screenshot.png")

​
Screenshot options

​
Capture mode

Three capture modes are available depending on how much of the page you need:
ParameterDescription
screenshot=trueCaptures the above-the-fold visible area only. Default behavior.
screenshot_fullpage=trueCaptures the entire page by scrolling and stitching the full content.
screenshot_selector=<CSS Selector>Captures only the element matched by the given CSS selector.
screenshot_fullpage and screenshot_selector are mutually exclusive. Use one or the other in a single request.

​
Image format and quality

By default, screenshots are returned as PNG. You can switch to JPEG for smaller file sizes using the following parameters:
ParameterValuesDescription
screenshot_formatpng, jpegSets the output format. Defaults to png.
screenshot_quality1 to 100Sets the JPEG compression quality. Only applies when screenshot_format=jpeg.
Full-page screenshots can exceed 10MB as PNG. If you are hitting size limits, switch to screenshot_format=jpeg and tune screenshot_quality to find the right balance between file size and visual fidelity.

​
Combining with other parameters

Screenshot requests are compatible with wait, wait_for, and js_instructions, which lets you control exactly when the capture happens. Use these when the page loads content after the initial render or requires user interaction before the target content is visible.
Find more details on our Wait Documentation, Wait For Selector Documentation, and JS Instructions Documentation.
When using json_response=true, the screenshot data is returned base64-encoded inside a JSON object instead of as raw binary, which makes it easier to handle in API workflows that expect structured responses.

​
When to use page screenshots

Screenshots are the right choice when you need a visual record of a page rather than its text or data. They work well for:
  • Visual monitoring: detect layout changes, broken pages, or UI regressions across time.
  • Page archiving: preserve a timestamped visual snapshot of how a page looked at a specific moment.
  • Element capture: isolate and capture specific UI components, charts, or widgets using screenshot_selector.
  • QA and testing: validate that pages render correctly across different URLs or conditions.
  • Reporting and sharing: generate visual page previews for dashboards, reports, or stakeholder communication.
If you need to extract text or structured data from the page rather than a visual snapshot, use response_type=markdown, response_type=plaintext, or the outputs parameter instead.

​
Best practices

Always include js_render=true:
Screenshot generation requires a full browser render. Requests without js_render=true will not return a valid image. Use wait or wait_for for pages with delayed content:
If the page loads content after the initial render, use wait (milliseconds) or wait_for (CSS selector) to ensure everything is visible before the screenshot is captured.
Find more details on our Wait Documentation or Wait For Selector Documentation.
Switch to JPEG for large full-page screenshots:
Full-page screenshots of long pages can exceed 10MB as PNG, which causes errors. Use screenshot_format=jpeg with screenshot_quality set between 60 and 85 for a good balance of clarity and file size. Save as binary, not text:
Screenshot files are binary. Always write the response body in binary mode (for example, "wb" mode in Python and Ruby, Buffer in Node.js, FileOutputStream in Java). Writing binary content as text will corrupt the image file. Credits are charged on successful responses:
A screenshot request is charged when the API returns a 200 status code, regardless of whether the image contains the content you expected. Because js_render=true is required, the JS rendering credit cost also applies. Test on a small set of URLs before running at scale.

​
Troubleshooting

The page likely loads content after the initial render. Add wait (in milliseconds) to give the page time to finish loading, or use wait_for with a CSS selector that is only present once the main content is visible.
You are likely writing the response as text instead of binary. Always use binary write mode in your language of choice ("wb" in Python and Ruby, Buffer in Node.js, FileOutputStream in Java) and write the raw response body. Image files are binary and writing them as text will produce a corrupt file.
Full-page screenshots of long pages can exceed 10MB as PNG. Switch to screenshot_format=jpeg and set screenshot_quality to a value between 60 and 85 to reduce the file size significantly while keeping the image readable.
Make sure the CSS selector you are passing targets a single, visible element. If the element is loaded dynamically, use wait_for with the same selector to ensure it is present in the DOM before the screenshot is taken. Avoid auto-generated or highly dynamic class names, as these can change between requests.
These two parameters are mutually exclusive. Use screenshot_fullpage=true when you want the entire page, and screenshot_selector when you want a specific element. You cannot use both in the same request.

​
Pricing

Screenshot requests are included at no additional cost beyond the standard JS rendering rate. Because screenshot generation requires js_render=true, all screenshot requests are billed at the JS rendering credit rate. You only pay extra for Premium Proxy when used.
You can monitor your ZenRows usage in multiple ways to stay informed about your account activity and prevent unexpected overages.Dashboard monitoring: View real-time usage statistics, remaining requests, success rates, and request history on your Analytics Page. You can also set up usage alerts in your notification settings to receive notifications when you approach your limits.Programmatic monitoring: For automated monitoring in your applications, call the /v1/subscriptions/self/details endpoint with your API key in the X-API-Key header. This returns real-time usage data that you can integrate into your monitoring systems. Learn more about the usage endpoint.Response header monitoring: Track your concurrency usage through response headers included with each request:
  • Concurrency-Limit: Your maximum concurrent requests
  • Concurrency-Remaining: Available concurrent request slots
  • X-Request-Cost: Cost of the current request

​
FAQ (Frequently Asked Questions)

Yes. Screenshot generation requires a full browser render. You must include js_render=true in every screenshot request. Requests without it will not return a valid image.
Screenshot requests are billed at the JS rendering credit rate because js_render=true is required. The screenshot parameters themselves do not add an extra cost beyond that.
Yes. Use screenshot_selector=<CSS Selector> to capture only the element matched by the selector. Note that screenshot_selector and screenshot_fullpage are mutually exclusive and cannot be used together.
PNG and JPEG are supported via the screenshot_format parameter. PNG is the default and is best for high-fidelity captures. JPEG offers smaller file sizes and is recommended for full-page screenshots or high-volume pipelines where storage and bandwidth matter.
No, the screenshot parameters are features of the Universal Scraper API. In Scraping Browser (CDP/Playwright) sessions, you can capture screenshots directly using Playwright’s built-in page.screenshot() method.
Yes. Add json_response=true to your request and the screenshot will be returned base64-encoded inside a JSON object. This is useful for workflows that expect structured API responses rather than raw binary streams.