How to Use a Screenshot API for Automated Website Screenshots

A screenshot API automates website captures by accepting a page URL and options, then returning an image or PDF as bytes, a URL, or a redirect. A typical job is: authenticate from a trusted server, send the URL and capture settings, then save or process the result. Use a hosted API when its controls and delivery model fit your workflow; use Playwright when you need to manage browser navigation and capture directly.

This guide shows both approaches, explains the capture options that affect output, and covers batching, reliability, costs, common errors, and when a managed API can remove browser setup.

1. Choose a capture route

Route	What you manage	Good fit when
Hosted screenshot API	HTTP request, credentials, request scheduling, and result handling	You want a managed endpoint with documented capture options
Playwright	Browser installation, launch, contexts, navigation, waits, and capture	Your application needs direct control over browser behavior or already runs browser automation

The route choice is an implementation tradeoff, not a universal reliability or cost ranking. Check each service’s current features, limits, security practices, data retention, and supported-site terms before using it for production or sensitive pages.

For hosted APIs, keep the API key on a trusted server. Screenshot API’s documentation recommends key authentication in a header; avoid putting secrets into browser JavaScript or public URLs. Provider-specific options, response formats, and limits vary. [Screenshot API authentication and request documentation](https://screenshotapi.net/documentation)

2. Make a basic hosted API request

Get an API key from the provider and read its request and response documentation. The example below uses Screenshot API’s documented endpoint and parameter names. It requests a PNG and saves the response body; check your account’s current documentation for authentication requirements and whether your chosen output is returned as bytes, a URL, or a redirect.

curl -G 'https://shot.screenshotapi.net/screenshot' \
  -H 'Accept: image/png' \
  --data-urlencode 'token=YOUR_API_KEY' \
  --data-urlencode 'url=https://example.com' \
  --data-urlencode 'output=image' \
  --data-urlencode 'file_type=png' \
  --output screenshot.png

Do not assume that every hosted API uses the same endpoint, key placement, or response body. Some return a CDN URL or redirect; in those cases, follow the provider’s documented result URL to retrieve the file. Screenshot API documents a flow that can return a CDN URL or redirect, as well as batch capture. [Screenshot API request documentation](https://screenshotapi.net/documentation)

3. Capture pages with Playwright

Install Playwright and its Chromium browser in the environment where the capture job will run. This runnable Node.js example opens a page, waits for navigation, takes a full-page PNG, and closes the browser even if capture fails.

npm install playwright
npx playwright install chromium

// screenshot.mjs
import { chromium } from 'playwright';

const url = process.argv[2] ?? 'https://example.com';
const browser = await chromium.launch({ headless: true });

try {
  const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
  await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
  await page.screenshot({ path: 'screenshot.png', fullPage: true });
} finally {
  await browser.close();
}

node screenshot.mjs https://example.com

Playwright’s documented workflow is to launch a browser, create a context and page, navigate, call page.screenshot, and close the browser. Its screenshot method can save a file or return bytes for post-processing. [Playwright screenshots guide](https://playwright.dev/docs/screenshots) · [Playwright Page API](https://playwright.dev/docs/api/class-page)

4. Choose the right capture area and output

Viewport, full page, or one element

Viewport: captures the visible browser area. Use it for previews, above-the-fold checks, or consistent viewport comparisons.
Full page: captures the scrollable page in one tall image. It can be useful for archival or review, but very long pages may produce unwieldy files; consider capturing sections if the consumer does not need one continuous image.
Element: captures a component such as a chart, form, or header. Confirm the selector or locator resolves after the page has rendered.

Screenshot API documents viewport, fullPage, and selector. Playwright supports full-page capture and locator screenshots. [Screenshot API options](https://screenshotapi.net/documentation) · [Playwright screenshots](https://playwright.dev/docs/screenshots)

Format, dimensions, and scale

PNG is a lossless choice for text and interface details. JPEG and WebP can be useful when a smaller raster file matters; validate the result for your downstream use. Screenshot API documents PNG, JPEG, WebP, and PDF output. Playwright documents PNG, JPEG, and WebP; its quality setting applies to JPEG and WebP, not PNG. Neither source establishes universal quality or file-size benchmarks.

Set viewport width and height to match the layout you want to capture. Device scale affects output pixel dimensions: a high-density scale produces more device pixels for the same CSS viewport and can increase image size. Playwright’s scale option distinguishes CSS pixels from device pixels. [Playwright screenshots guide](https://playwright.dev/docs/screenshots)

Wait for the content that matters

A navigation event does not prove that every dynamic widget or image has finished rendering. Choose a wait condition based on the content: wait for a selector that marks the target section ready, wait for an application-specific state, or add a short delay only when the page has known late-arriving content. Screenshot API documents navigation wait states, selector waits, and a delay. A fixed delay alone is not a guarantee.

await page.goto('https://example.com/dashboard', { waitUntil: 'domcontentloaded' });
await page.locator('[data-capture-ready="true"]').waitFor({ state: 'visible', timeout: 15_000 });
await page.screenshot({ path: 'dashboard.png', fullPage: true });

For repeatable captures, handle predictable consent dialogs or overlays deliberately. Playwright documents screenshot styles that can hide or change dynamic elements and recommends dismissing predictable overlays in the normal flow. [Playwright Page API](https://playwright.dev/docs/api/class-page)

5. Configure repeat and batch captures

Define a capture manifest. Store each URL with its viewport, output format, capture area, and readiness condition. Keep secrets out of the manifest if it is checked into source control.
Set concurrency deliberately. Start with a small number of parallel jobs, then adjust based on provider rate limits or the capacity of your own browser workers. Do not assume the destination sites can handle unlimited requests.
Use batching when available. Screenshot API documents a batch endpoint that returns a batch ID for tracking. Inspect its current documentation for per-batch limits and completion behavior.
Make retries bounded. Retry transient network or provider errors with backoff and a maximum attempt count. Avoid retrying permanent errors such as invalid credentials or malformed URLs.
Record outcomes. Keep the requested URL, options, timestamp, status, output location, and error category so failed captures can be diagnosed without silently replacing useful results.

Caching changes freshness and repeat-run work. Screenshot API documents a default cache TTL of 86,400 seconds and stale TTL of 43,200 seconds; these are vendor-specific values and should be rechecked before depending on them. The same documentation lists free-plan limits of 60 requests per minute and 500 screenshots per month. Check current plan terms and response headers before estimating throughput. [Screenshot API limits and caching documentation](https://screenshotapi.net/documentation)

6. Troubleshoot common capture failures

Symptom	Likely cause	What to do
401 or 403 response	Missing, invalid, expired, or incorrectly placed API key; account access restriction	Verify credentials and the provider’s required authentication method from the server environment. Never move the key into public client code.
HTML or JSON saved with a .png extension	The API returned an error document or a URL/redirect rather than image bytes	Inspect status, content type, headers, and response body before saving. Follow the documented redirect or fetch the returned image URL.
Blank or incomplete capture	Navigation completed before the relevant content rendered, or the page failed to load	Wait for a meaningful selector or app state, confirm the page is reachable from the capture environment, and inspect the captured response status.
Element capture fails	Selector matches nothing, matches too early, or is hidden	Wait for the locator or selector to become visible; check the selector against the rendered page and account for iframes or shadow roots if relevant.
Overlay covers the content	Consent dialog, sign-up modal, or chat widget is in the page’s normal flow	Dismiss it as a visitor would, or use a documented hide/style option if appropriate. Do not assume a screenshot tool removes overlays automatically.
Timeout	Slow navigation, network-idle never reached, or a selector never appears	Use the narrowest useful wait condition, set an appropriate timeout, and capture diagnostic status. Avoid treating a longer timeout as proof of success.
Rate limit or quota error	Request rate or monthly usage exceeded	Read the current plan and rate-limit headers, reduce concurrency, schedule work, use caching where freshness allows, or select an adequate plan.
Browser process crashes or is missing	Browser binary was not installed, worker memory is constrained, or browser lifecycle cleanup is incomplete	Install the required browser, close pages and browsers in cleanup paths, and limit concurrent contexts according to available resources.

7. Performance, reliability, and cost

Capture time depends on target-site response and rendering, the wait strategy, output dimensions, and the chosen provider or browser environment. The research sources do not establish cross-provider speed, reliability, or cost benchmarks. Measure your own workload with representative pages before setting a schedule or service-level expectation.

Reduce wasted work: use cache only when its freshness window suits the page, and avoid full-page captures when a viewport or element is sufficient.
Protect throughput: respect documented request limits, queue work, and use bounded concurrency. For self-managed Playwright, account for the browser processes and resources your workers need.
Handle failure as data: distinguish navigation errors, timeouts, provider errors, and valid captures of pages that happen to be empty. Save diagnostic metadata with the output.
Estimate total cost: include API plan or usage fees where applicable, plus infrastructure and engineering time for self-managed browsers. Recheck changing vendor prices, quotas, and cache terms.
Review sensitive-page handling: verify credentials, data retention, geographic processing, and permitted use directly with the chosen provider before capturing private or regulated content.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It accepts one GET request with a URL and returns a PNG, JPEG, WebP, or PDF. The parameter names used by other screenshot APIs also work, which can make a switch easier. Its capture options include full-page and CSS selector capture, viewport and device presets, wait conditions, custom CSS and JavaScript, cookies and headers, PDF settings, caching, signed image links, async jobs, and bulk capture for up to 100 URLs per call.

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Cookie banners are accepted like a visitor and 60+ known consent platforms, newsletter popups, and chat widgets are removed before the shot; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

9. Frequently asked questions

Only if the provider supports the required authenticated session and its terms allow the capture. Check its documented cookie or authorization options and avoid sending credentials to a service without reviewing its handling practices.

Should I use screenshots for visual regression tests?

They can provide images to compare, but repeatability depends on controlling viewport, scale, dynamic content, fonts, overlays, and timing. Use a stable capture setup and define how your comparison handles expected changes.

Can I capture a whole site in one request?

A page screenshot captures a URL. Site-wide jobs usually need a URL list or crawl process, followed by queued captures. Check whether the provider offers batch submission and what its batch limits are.

Is a longer timeout always safer?

No. A timeout can accommodate a slow target, but it does not establish that the page reached the desired state. Wait for the content you need and report the capture outcome clearly.