Async Screenshots & Storage

Capturing a screenshot of a heavy, JavaScript-driven page can take longer than an HTTP request should stay open. POST /v1/screenshot with async=true returns immediately with a 202 and a pre-signed download_url; the capture runs in the background and the object appears in object storage when it's done.

This page covers the async contract in detail — status codes, polling, storage requirements, and parallel capture patterns. For the endpoint's full parameter list (viewport, device presets, cookies, resource blocking), see Screenshot & PDF Capture.

The async contract

curl -X POST "https://scrape.toolkitapi.io/v1/screenshot?async=true" \
  -H "x-api-key: $TOOLKIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "full_page": true}'

Immediately returns:

HTTP/1.1 202 Accepted
Retry-After: 3
Content-Type: application/json

{
  "status": "processing",
  "download_url": "https://storage.toolkitapi.io/screenshots/2026/10/20/ab12cd34.png",
  "message": "Screenshot is being captured. Poll the download_url - returns 200 when ready, 404 while processing."
}

Then poll download_url directly — not the API endpoint:

download_url response Meaning
404 Still processing (object not uploaded yet)
200 + image body Done — save it, or just use the URL
403 Pre-signed link expired; start a new capture

The Retry-After: 3 header on the 202 is a hint to poll roughly every 3 seconds. There is no job id and no status endpoint: the object's existence is the status.

Requirements

  • Object storage must be configured. If MinIO/S3 env vars are absent, async=true fails fast with 400. Sync captures still work without storage — they return the image inline.
  • The download_url is pre-signed. Treat it as a secret for its lifetime: anyone with the link can fetch the image. Don't log it to public places or embed it in client-side HTML long-term; re-host the bytes if you need a permanent URL.

Python: submit, poll, save

import io, time, requests
from PIL import Image

API_KEY = "YOUR_KEY"
BASE = "https://scrape.toolkitapi.io"

def capture_async(url: str, *, full_page: bool = True,
                  timeout: float = 120, interval: float = 3) -> bytes:
    resp = requests.post(
        f"{BASE}/v1/screenshot",
        params={"async": "true"},
        headers={"x-api-key": API_KEY},
        json={"url": url, "full_page": full_page},
        timeout=30,
    )
    resp.raise_for_status()
    download_url = resp.json()["download_url"]

    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        r = requests.get(download_url, timeout=30)
        if r.status_code == 200:
            return r.content
        if r.status_code != 404:
            r.raise_for_status()
        time.sleep(interval)

    raise TimeoutError(f"capture not ready after {timeout}s: {url}")

png = capture_async("https://example.com")
Image.open(io.BytesIO(png)).save("example.png")

JavaScript: submit, poll, upload

async function captureAsync(url, { fullPage = true, timeoutMs = 120_000 } = {}) {
  const submit = await fetch(
    "https://scrape.toolkitapi.io/v1/screenshot?async=true",
    {
      method: "POST",
      headers: {
        "x-api-key": process.env.TOOLKIT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ url, full_page: fullPage }),
    },
  );
  if (submit.status !== 202) throw new Error(`submit failed: ${submit.status}`);
  const { download_url } = await submit.json();

  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const r = await fetch(download_url);
    if (r.ok) return Buffer.from(await r.arrayBuffer());
    if (r.status !== 404) throw new Error(`poll failed: ${r.status}`);
    await new Promise((res) => setTimeout(res, 3000));
  }
  throw new Error(`capture timed out: ${url}`);
}

Capturing many pages

Each 202 starts an independent background task. Submit all of them, then poll everything — don't serialise submit-then-wait per URL, or a 50-page run takes 50 × page-time instead of ~max(page-times).

import requests, time
from concurrent.futures import ThreadPoolExecutor

def submit(url):
    r = requests.post(
        "https://scrape.toolkitapi.io/v1/screenshot",
        params={"async": "true"},
        headers={"x-api-key": API_KEY},
        json={"url": url, "full_page": True},
        timeout=30,
    )
    r.raise_for_status()
    return url, r.json()["download_url"]

def wait(download_url, timeout=180):
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        r = requests.get(download_url, timeout=30)
        if r.status_code == 200:
            return r.content
        if r.status_code != 404:
            r.raise_for_status()
        time.sleep(3)
    return None

urls = load_urls()
with ThreadPoolExecutor(max_workers=8) as pool:
    jobs = list(pool.map(submit, urls))
    results = dict(zip(urls, pool.map(lambda j: wait(j[1]), jobs)))

ok = {u: b for u, b in results.items() if b}
print(f"{len(ok)}/{len(urls)} captured")

Keep concurrency moderate (≈8 workers). The API rate-limits per key and each capture spins a real browser.

Thumbnails

Sync responses can include a small base64 thumbnail, which is a good fit for "grid of previews" UIs where you don't want to download 50 full-resolution PNGs:

curl -G "https://scrape.toolkitapi.io/v1/screenshot" \
  -H "x-api-key: $TOOLKIT_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "thumbnail=true" \
  --data-urlencode "thumbnail_width=320"

Store the thumbnail inline and lazily fetch the async full-size image only when a user opens the preview.

When to use sync vs async

Situation Use
One page, under ~20 s, image needed immediately Sync (default)
Heavy SPA, video, or long wait_for Async
Batch of 20+ pages Async
Browser/client can't hold a long connection (mobile, serverless with short limits) Async
No object storage configured Sync only

Errors

Status Condition
400 async=true but object storage isn't configured; or the url is invalid / SSRF-blocked
401 Missing / invalid API key
422 Missing required body field (url)
429 Rate limit hit — back off and retry
500 Browser failed to launch or navigate

A background capture that fails is only visible as a download_url that never turns 200 — always enforce your own timeout, as in the examples above.

See also