Screenshot API Best Practices: Format, Timing, and Reliability

Screenshot APIs are deceptively simple to get started with and deceptively tricky to operate reliably at scale. This guide covers the most common issues teams hit and how to avoid them.

Choosing the right format

• **PNG** — lossless, ideal for UI screenshots and QA pipelines. Larger file size.
• **JPEG** — lossy, 60–80% smaller than PNG. Good for thumbnails and previews where compression is acceptable.
• **WEBP** — best compression with quality comparable to PNG. Use for web delivery.
• **PDF** — if you need a printable output from a screenshot context.

Timing and JS rendering

The most common issue: capturing a page before JS has finished rendering. Always use wait_for with a CSS selector that signals page completion:

{
  "url": "https://yourapp.com/dashboard",
  "wait_for": "#chart-rendered"
}

If no reliable selector exists, use a delay as a fallback — but prefer explicit selectors.

Blocking distractions

Cookie banners, chat widgets, and ads ruin screenshots. Always enable block_ads: true for clean captures. For screenshots used in OG images or customer-facing contexts, this is essential.

Reliability at scale

Use async mode for bulk capture jobs. Synchronous requests time out and retry logic becomes complex. With async mode, you get a job ID immediately and a webhook when the result is ready.