Script Snapshot Site into batch jobs, QA pipelines, and automation flows

Python screenshot API workflows

The official snapshot-site-sdk package gives Python applications a small client for screenshots, rendered-page analysis, visual comparison, and asset download. It fits recurring operational work: scheduled scripts, QA pipelines, content review, internal services, and jobs that process an approved list of URLs.

The current SDK requires Python 3.9 or later. It uses the production Snapshot Site API by default and allows a custom base URL when an authorized environment requires one.

Configure credentials outside the script

Read the API key from an environment variable or secret manager. A key written directly into a script, notebook cell, example output, or repository can be copied long after the original job finishes.

import os
from snapshot_site import SnapshotSiteClient

client = SnapshotSiteClient(
    api_key=os.environ["SNAPSHOT_SITE_API_KEY"]
)

Fail clearly when the variable is missing. In CI or a scheduler, configure the secret in the platform rather than generating a local .env file during the job. Avoid printing client configuration in debug output.

Select the method for the result you need

Capture with screenshot()

Use screenshot() to create an image or PDF from a URL. Specify width so the responsive layout is intentional. Set fullSize when the complete document matters, and use the smallest reliable delay for late content. See full-page screenshots for long-page decisions.

Analyze with analyze()

Use analyze() when the rendered page should produce summary or quality information with the capture. AI output supports triage and review; preserve the URL and screenshot when a person may need to verify the generated result.

Compare with compare()

Use compare() for release QA and monitored baselines. Configure both states identically and use the returned diff image to interpret mismatch metrics. The visual regression guide covers threshold and baseline practices.

Save with download_to()

Use download_to() with a direct asset URL or supported response mapping. Choose the output path in trusted application code, create parent directories deliberately, and never concatenate an untrusted filename without validation.

Design a reliable URL batch

A list of URLs turns a simple API call into an operational workflow. Validate each input, normalize the scheme, and attach a stable internal identifier. Process results independently so one bad URL does not discard the rest of the run.

def capture_one(item):
    return client.screenshot({
        "url": item["url"],
        "format": "webp",
        "width": 1440,
        "fullSize": True,
        "hideCookie": True,
        "delay": 2,
    })

for item in approved_urls:
    try:
        result = capture_one(item)
        save_result(item["id"], result)
    except Exception as exc:
        record_failure(item["id"], exc)

Sequential processing is a clear starting point. When throughput becomes a measured constraint, add a bounded worker pool or queue. Do not submit an entire large dataset concurrently without regard for memory, retries, or service limits.

Checkpoint progress after each item or small batch. A restarted job should resume from incomplete work rather than recapture every successful page.

Python QA and monitoring patterns

Release comparison

Capture production and preview URLs with the same configuration, call compare(), and attach the diff image to the release record. Keep approval separate from baseline replacement so an unexpected change cannot approve itself.

Content inventory

Use analyze() over an authorized URL set to help classify and prioritize pages. AI-generated summaries are review aids, not canonical content records. For exact fields, use deterministic extraction or validation.

Scheduled website monitoring

Store a known-good image, capture the live page on a schedule, and compare the two. Route meaningful differences with before, after, and diff context. The website monitoring page explains baseline lifecycle and alert design.

Asset generation

Use screenshot output for documentation, internal previews, or approved marketing workflows. Cache stable results instead of recapturing the same page every time a downstream consumer asks for it.

Error and retry handling

Classify errors before retrying. Invalid URLs, missing credentials, and rejected payloads need correction. Timeouts or temporary transport failures may justify a bounded retry with backoff. Store the attempt count and final state with the URL record.

Sanitize logged URLs when query parameters may contain credentials or personal data. Log internal job identifiers and status, not the API key. Restrict access to downloaded captures according to the sensitivity of the source page.

Performance and storage

Use viewport capture when only the visible fold is needed. Full-page mode renders more content and should serve a concrete requirement. Keep delay small and evidence-based. Prevent overlapping scheduled runs from processing the same queue twice.

Select PNG for lossless UI detail, WebP or JPEG for lighter previews, and PDF for document output. Preserve the original when it is evidence and derive thumbnails separately.

Common Python integration mistakes

• Hardcoding the key in a script or notebook.
• Sending a large URL list with unbounded concurrency.
• Losing completed work when one batch item fails.
• Writing assets to unvalidated paths.
• Retrying permanent errors indefinitely.
• Comparing screenshots created with different settings.
• Treating AI output as exact extracted data.

Use the API documentation for request fields and the SDK repository for current compatibility. Validate one representative workflow before scaling it across a dataset.