The Developer's Guide to the Screenshots API

Supacrawler's Screenshots API provides granular control over every aspect of how a webpage is rendered and captured. This guide provides a definitive walkthrough of every feature, with practical code examples for common use cases.

By the end of this guide, you will know how to:

Capture screenshots for different devices and custom dimensions.
Block ads, cookies, and specific CSS selectors to create clean captures.
Emulate user preferences like dark mode and high contrast.
Manage screenshot URLs for long-term storage.

1. Basic Desktop & Mobile Screenshots

Let's start with the fundamentals. A basic desktop screenshot captures the above-the-fold content at standard desktop resolution.

Basic Desktop Screenshot

from supacrawler import SupacrawlerClient
from supacrawler.scraper_client.models import (
    ScreenshotCreateRequest, 
    ScreenshotCreateRequestFormat,
    ScreenshotCreateRequestDevice
)

client = SupacrawlerClient(api_key='YOUR_API_KEY')

job = client.create_screenshot_job(ScreenshotCreateRequest(
    url="https://antoineross.com",
    device=ScreenshotCreateRequestDevice.DESKTOP,
    format_=ScreenshotCreateRequestFormat.PNG,
    full_page=False
))

result = client.wait_for_screenshot(job.job_id, timeout_seconds=30)
print(f"Screenshot URL: {result.screenshot_url}")

2. Format, Quality, and Full Page Captures

Control the file type with format, its compression with quality (for JPEG/WebP), and capture the entire page with full_page.

Full-Page Mobile Screenshot with JPEG Optimization

from supacrawler import SupacrawlerClient
from supacrawler.scraper_client.models import ScreenshotCreateRequest, ScreenshotCreateRequestFormat, ScreenshotCreateRequestDevice

client = SupacrawlerClient(api_key='YOUR_API_KEY')

job = client.create_screenshot_job(ScreenshotCreateRequest(
    url="https://antoineross.com",
    device=ScreenshotCreateRequestDevice.MOBILE,
    format_=ScreenshotCreateRequestFormat.JPEG,
    quality=85,
    full_page=True
))

result = client.wait_for_screenshot(job.job_id)
print(f"File size: {result.metadata.get('file_size')} bytes")

Full-page mobile screenshot of antoineross.com — A full-page mobile capture using JPEG format for a smaller file size.

3. Custom Dimensions & Accessibility Emulation

Set a CUSTOM device to specify exact dimensions. You can also emulate user accessibility preferences like dark_mode or high_contrast.

Custom Size with Dark Mode

from supacrawler import SupacrawlerClient
from supacrawler.scraper_client.models import ScreenshotCreateRequest, ScreenshotCreateRequestDevice

client = SupacrawlerClient(api_key='YOUR_API_KEY')

job = client.create_screenshot_job(ScreenshotCreateRequest(
    url="https://hikari.antoineross.com",
    device=ScreenshotCreateRequestDevice.CUSTOM,
    width=1200,
    height=800,
    dark_mode=True,
    format_=ScreenshotCreateRequestFormat.PNG
))

result = client.wait_for_screenshot(job.job_id, timeout_seconds=30)
print(f"Dark mode screenshot: {result.screenshot_url}")

Dark mode screenshot of a website at a custom 1200x800 resolution. — A 1200x800 capture with dark mode enabled.

4. Advanced Content Blocking

Create clean, focused screenshots by blocking ads, cookie banners, trackers, and even resource types like images or fonts. You can also hide specific elements with CSS selectors.

Advanced Content Blocking

from supacrawler import SupacrawlerClient
from supacrawler.scraper_client.models import ScreenshotCreateRequest, ScreenshotCreateRequestBlockResourcesItem

client = SupacrawlerClient(api_key='YOUR_API_KEY')

job = client.create_screenshot_job(ScreenshotCreateRequest(
    url="https://www.quora.com/Which-website-has-the-most-ads",
    device=ScreenshotCreateRequestDevice.DESKTOP,
    format_=ScreenshotCreateRequestFormat.PNG,
    
    # Block unwanted content
    block_ads=True,
    block_cookies=True,
    block_trackers=True,
    block_resources=[
        ScreenshotCreateRequestBlockResourcesItem.IMAGE,
        ScreenshotCreateRequestBlockResourcesItem.FONT
    ],
    hide_selectors=["footer", ".social-links"],
))

Screenshot of a Quora page with all ads, cookies, images, and fonts blocked. — A text-only render of a webpage with all non-essential resources and elements removed.

5. Advanced Wait Strategies

Control exactly when the screenshot is taken using wait_until, wait_for_selector, and delay.

domcontentloaded: (Fastest) Waits only for the initial HTML document to be loaded and parsed.
networkidle: (Most complete) Waits until there are no more network connections for at least 500 ms.
wait_for_selector: Waits for a specific CSS selector to be visible in the DOM.

Wait for a Specific Element

from supacrawler import SupacrawlerClient
from supacrawler.scraper_client.models import ScreenshotCreateRequest, ScreenshotCreateRequestWaitUntil

client = SupacrawlerClient(api_key='YOUR_API_KEY')

# Wait for the main content of a Single-Page Application to load
job = client.create_screenshot_job(ScreenshotCreateRequest(
    url="https://spa-example.com",
    wait_for_selector="#main-content",
    wait_until=ScreenshotCreateRequestWaitUntil.NETWORKIDLE,
    delay=1, # Add an extra 1s wait after conditions are met
    timeout=30
))

6. Authentication and Localization

Use headers and cookies to capture pages that require authentication or to request content in a specific language.

Capture Authenticated Content in a Specific Language

from supacrawler import SupacrawlerClient
from supacrawler.scraper_client.models import ScreenshotCreateRequest, ScreenshotCreateRequestCookiesItem

client = SupacrawlerClient(api_key='YOUR_API_KEY')

job = client.create_screenshot_job(ScreenshotCreateRequest(
    url="https://github.com/dashboard",
    headers={ "Accept-Language": "de-DE,de;q=0.9" },
    cookies=[
        ScreenshotCreateRequestCookiesItem(
            name="user_session",
            value="your_session_token",
            domain="github.com"
        )
    ]
))

URL Management and Production Tips

URL Expiry: Screenshot URLs are signed and expire after 15 minutes. For long-term storage, you must download the image file.
URL Renewal: You can get a fresh 15-minute URL for a completed job by calling the get_screenshot endpoint with the job ID.
Performance: For the fastest captures and smallest file sizes, use jpeg or webp format, block all non-essential resources, and use the domcontentloaded wait strategy.

Next Steps

This guide covers the core functionality of the Screenshots API. To explore all available parameters and options, check out the full API documentation.