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=truefails fast with400. Sync captures still work without storage — they return the image inline. - The
download_urlis 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¶
- Screenshot & PDF Capture — full parameter reference for screenshot, PDF, and element capture
- Browser Engines & Devices — choosing chromium/firefox/webkit and device presets
- Rendering & Proxies — JavaScript rendering and proxy options