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.
- 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. - Send the request.
POST /v1/screenshotswith anAuthorization: Bearerheader and a JSON body.urlis the only required field. - Choose a device and format.
devicesets the viewport (defaultdesktop) andformatispng,jpegorwebp. - Capture the full page if needed.
fullPage: truecaptures the whole scrollable page instead of the first viewport. - Add a device frame (optional).
frame: trueplaces the capture inside device artwork. Frames are disabled for full-page captures. - Leave cleanup on to hide banners and ads.
cleanupdefaults totrue. Details are in removing cookie banners from screenshots. - Save the image. The response body is the image. The
X-Screenshot-IdandX-Expires-Atheaders identify the stored copy, which you can fetch again for two days. - Handle errors and rate limits. Errors are JSON with a stable
code. Retry429,503and504with 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 --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
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()));
import osimport requestsresponse = 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.
| Field | Values | Default |
|---|---|---|
| url | string | required |
| device | device id | desktop |
| format | png | jpeg | webp | png |
| fullPage | boolean | false |
| cleanup | boolean | true |
| frame | boolean | false |
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.
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…"}}
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request | Fix the body; do not retry unchanged. |
| 401 | unauthorized | Check the key is present and not revoked. |
| 402 | subscription_required | The account needs an active Pro subscription. |
| 429 | rate_limited | Wait for the Retry-After header, then retry. |
| 429 | daily_limit_reached | Wait until 00:00 UTC; X-RateLimit-Reset gives the time. |
| 502 | capture_failed | The site blocked the browser or errored. Check the URL in a normal browser. |
| 503 | capture_unavailable | Retry with backoff. |
| 503 | capture_finalization_pending | Fetch the result later using the X-Screenshot-Id header. |
| 504 | capture_timeout | The 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
frametogether withfullPage. 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
400or402in a loop. Only429,503and504are worth retrying.
Where to go next
- API reference for every option and device.
- Remove cookie banners from screenshots.
- Pricing: Pro is $20 per month.
- Screenshot API vs running Puppeteer yourself.