How to take a website screenshot with an API

By URLBooth · Published · Last updated

To take a website screenshot with an API, send an authenticated POST request containing the page URL to a screenshot endpoint. The service loads the page in a real browser and returns the image in the response. With URLBooth you create a key, post {"url": "https://example.com"} to /v1/screenshots and save the bytes, usually within a few seconds.

How do you take a screenshot with the URLBooth API?

The whole flow is one HTTP request. There is no job to poll: the image comes back in the response to the same request.

  1. Get an API key. Sign in with Google or GitHub, subscribe to Pro and create a key under API keys. Keys start with sk_ and are shown once. See pricing for what Pro includes.
  2. Send the request. POST /v1/screenshots with an Authorization: Bearer header and a JSON body. url is the only required field.
  3. Choose a device and format. device sets the viewport (default desktop) and format is png, jpeg or webp.
  4. Capture the full page if needed. fullPage: true captures the whole scrollable page instead of the first viewport.
  5. Add a device frame (optional). frame: true places the capture inside device artwork. Frames are disabled for full-page captures.
  6. Leave cleanup on to hide banners and ads. cleanup defaults to true. Details are in removing cookie banners from screenshots.
  7. Save the image. The response body is the image. The X-Screenshot-Id and X-Expires-At headers identify the stored copy, which you can fetch again for two days.
  8. Handle errors and rate limits. Errors are JSON with a stable code. Retry 429, 503 and 504 with backoff.

What do the requests look like in curl, Node.js and Python?

Each example sends the key from the URLBOOTH_API_KEY environment variable and writes the returned bytes to a file. Keep the key on your server, never in browser or mobile code.

curl example
curl --fail-with-body "https://urlbooth.com/v1/screenshots" \
-H "Authorization: Bearer $URLBOOTH_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","device":"desktop","format":"png"}' \
-o screenshot.png
Node.js example
import { writeFile } from "node:fs/promises";
​
const response = await fetch("https://urlbooth.com/v1/screenshots", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.URLBOOTH_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://example.com",
device: "iphone-17-pro",
format: "webp",
fullPage: false,
}),
});
​
if (!response.ok) {
const { error } = await response.json();
throw new Error(`${error.code}: ${error.message}`);
}
​
console.log("id", response.headers.get("X-Screenshot-Id"));
await writeFile("screenshot.webp", Buffer.from(await response.arrayBuffer()));
Python example
import os
import requests
​
response = requests.post(
"https://urlbooth.com/v1/screenshots",
headers={"Authorization": f"Bearer {os.environ['URLBOOTH_API_KEY']}"},
json={
"url": "https://example.com",
"device": "desktop",
"format": "png",
"fullPage": True,
},
timeout=60,
)
​
if not response.ok:
error = response.json()["error"]
raise RuntimeError(f"{error['code']}: {error['message']}")
​
print("id", response.headers["X-Screenshot-Id"])
with open("screenshot.png", "wb") as file:
file.write(response.content)

Which options can you set?

These are the six request fields. Unknown fields are rejected, so a typo returns a 400 instead of silently changing the result. Device ids, limits and the full reference are in the API docs.

FieldValuesDefault
urlstringrequired
devicedevice iddesktop
formatpng | jpeg | webppng
fullPagebooleanfalse
cleanupbooleantrue
framebooleanfalse

How do you get the image back later?

Every successful capture is stored privately for two days. Use the X-Screenshot-Id header value to download it again, or to recover a capture when the response was lost.

Download a stored screenshot
curl "https://urlbooth.com/v1/screenshots/$ID/image" \
-H "Authorization: Bearer $URLBOOTH_API_KEY" \
-o screenshot.png

How should you handle errors and rate limits?

Failed requests return JSON with a stable code and a requestId to quote when reporting a problem. Limits on Pro are 60 requests per minute, 10 concurrent captures and 10,000 screenshots per day (reset at 00:00 UTC); failed captures are not counted.

{
"error": {
"code": "rate_limited",
"message": "…",
"requestId": "b9e1…"
}
}
StatusCodeWhat to do
400invalid_requestFix the body; do not retry unchanged.
401unauthorizedCheck the key is present and not revoked.
402subscription_requiredThe account needs an active Pro subscription.
429rate_limitedWait for the Retry-After header, then retry.
429daily_limit_reachedWait until 00:00 UTC; X-RateLimit-Reset gives the time.
502capture_failedThe site blocked the browser or errored. Check the URL in a normal browser.
503capture_unavailableRetry with backoff.
503capture_finalization_pendingFetch the result later using the X-Screenshot-Id header.
504capture_timeoutThe page did not finish loading or rendering in time. Retry once, then investigate the page or capture the viewport instead of the full page.
async function capture(body, attempts = 3) {
for (let attempt = 1; ; attempt++) {
const response = await fetch("https://your-domain.com/v1/screenshots", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.URLBOOTH_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify(body),
});
if (response.ok) return Buffer.from(await response.arrayBuffer());
const retryable = [429, 503, 504].includes(response.status);
if (!retryable || attempt === attempts) {
const { error } = await response.json();
throw new Error(`${error.code} (request ${error.requestId})`);
}
const wait = Number(response.headers.get("Retry-After")) || 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, wait * 1000));
}
}

Requests time out after about 45 seconds, so set your HTTP client timeout above that.

What are common mistakes?

  • Parsing the response as JSON. On success the body is the raw image; only errors are JSON. Read it as bytes.
  • Calling the API from the browser. That exposes your key; call it from your server.
  • Requesting frame together with fullPage. Frames are disabled for full-page captures.
  • Passing private or local addresses such as http://localhost:3000. Only public http and https URLs are captured.
  • Treating cleanup as guaranteed. It is best effort, and pages that block automated browsers can still fail.
  • Retrying 400 or 402 in a loop. Only 429, 503 and 504 are worth retrying.

Where to go next