How to Capture Screenshots of a List of URLs in Browshot

For a short list, use Browshot’s /api/v1/screenshot/multiple endpoint and repeat the url parameter for each page. The endpoint documents up to 10 URLs and up to 10 browser instances per request, allowing up to 100 URL-and-instance combinations. For a larger list, use /api/v1/batch/create with a text file containing one URL per line, or submit the file through Browshot’s dashboard. See the Browshot API documentation for current request and response details.

1. Choose the workflow for your list size

Workflow	Input	Use it for	Result handling
screenshot/multiple	Repeat url parameters; optionally repeat instance_id	A modest list of up to 10 URLs, with up to 10 instances	Multiple screenshot requests; check their status and retrieve each completed image
batch/create	Uploaded text file, one URL per line	Hundreds or thousands of URLs	Batch output can be delivered as a ZIP archive
Dashboard batch workflow	Upload a text file with one URL per line	One-off or manual bulk capture	Retrieve the resulting batch output in the dashboard

The multiple endpoint’s 10-URL limit is a per-request ceiling, not an unlimited list upload. You can make several requests for a longer list, but for hundreds or thousands of entries the batch workflow is a better fit. Browshot’s documentation says screenshots can be requested for a particular instance; the multiple endpoint uses instance 12 by default when none is supplied. Confirm instance availability and account requirements in the current API documentation.

2. Capture a short list with the multiple endpoint

In the request below, replace YOUR_API_KEY with your key and edit the URL values. This example uses one instance for each URL. Use the API key privately; avoid committing it to source control or exposing it in client-side code.

cURL

curl -G 'https://api.browshot.com/api/v1/screenshot/multiple' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'url=https://example.com/' \
  --data-urlencode 'url=https://www.python.org/' \
  --data-urlencode 'instance_id=12'

Repeated query parameters matter: send a separate url field for every page. URL-encode the values so query characters in a target address are not mistaken for Browshot request parameters. The response identifies the screenshot requests; use the returned IDs to check progress and obtain the finished images according to the API reference.

Python

import time
import requests

API_KEY = "YOUR_API_KEY"
ENDPOINT = "https://api.browshot.com/api/v1/screenshot/multiple"
urls = ["https://example.com/", "https://www.python.org/"]

response = requests.get(
    ENDPOINT,
    params=[("key", API_KEY), *( ("url", url) for url in urls), ("instance_id", "12")],
    timeout=60,
)
response.raise_for_status()
data = response.json()
print(data)

This submits the request and prints Browshot’s response so you can inspect the returned screenshot IDs and status information. Response shapes can depend on the endpoint and API version; use the fields documented for your account to poll individual requests and download completed results. Do not assume the submission call itself means every screenshot has finished.

Node.js

const endpoint = new URL("https://api.browshot.com/api/v1/screenshot/multiple");
endpoint.searchParams.set("key", process.env.BROWSHOT_API_KEY ?? "YOUR_API_KEY");
endpoint.searchParams.append("url", "https://example.com/");
endpoint.searchParams.append("url", "https://www.python.org/");
endpoint.searchParams.append("instance_id", "12");

const response = await fetch(endpoint);
if (!response.ok) {
  throw new Error(`Browshot request failed: ${response.status} ${await response.text()}`);
}
console.log(await response.json());

In a deployed application, supply the key through a secret or environment variable instead of hard-coding it. This snippet submits the capture request and prints the response; status checks and downloads are follow-up steps.

Capture the same pages with different instances

Repeat instance_id when you need each URL rendered by more than one browser instance. With two URLs and two instances, Browshot documents four combinations. Keep the number of URLs and instances at or below 10 apiece for this endpoint.

curl -G 'https://api.browshot.com/api/v1/screenshot/multiple' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'url=https://example.com/' \
  --data-urlencode 'url=https://www.python.org/' \
  --data-urlencode 'instance_id=12' \
  --data-urlencode 'instance_id=22'

3. Submit a large list as a batch

Create a plain text file with one complete URL on each line. Avoid extra separators such as commas: each line is one target.

https://example.com/
https://www.python.org/
https://developer.mozilla.org/

The batch endpoint requires an instance ID and accepts the file as a multipart upload. The exact multipart field names and response fields should be taken from the current Browshot batch API reference; do not assume the repeated-query format from screenshot/multiple applies to batch upload. The dashboard also supports uploading a text file with one URL per line. Batch results can be delivered as a ZIP archive.

Before submitting a large batch, validate that the file contains the intended URLs, each line is a valid absolute URL, and the chosen instance is available to your account. Keep a copy of the input file so you can match output files or failed entries to their source URLs.

4. Set capture behavior intentionally

Setting	Documented behavior	When to use it
size	screen is the default; page captures the full page	Use screen for the visible viewport, or page when the full document is needed
cache	Can reuse a recent screenshot for the same URL and instance; documented default is 24 hours	Use cached output for repeat captures where freshness is not essential; set cache=0 to request a fresh capture
delay	Waits after page load before capture; the documentation currently lists a default and range	Increase the delay when client-side rendering needs additional time; check the live reference for the supported range

The multiple endpoint accepts the parameters supported by screenshot/create. Check Browshot’s current reference for the exact accepted values and any changes. A delay is not a guarantee that every asynchronous widget or late network request has completed, so choose a value appropriate to the pages you capture.

5. Track completion and retrieve output

1. Submit the multiple request or batch and retain the returned identifier or identifiers.
2. Check the request status. Documented screenshot states include in_queue, processing, finished, and error.
3. For an individual screenshot, wait until it is finished, then retrieve its image using the documented information and download flow.
4. For a batch, retrieve the completed archive using the batch result information documented for your request.
5. Record failures alongside the original URLs, so a retry can target only the entries that need another attempt.

Do not treat a submitted request as a completed image. A capture may remain queued or processing before it is ready. For batch jobs, Browshot’s 2020 blog post says screenshots that fail because a URL is temporarily unavailable are retried up to three times before the service gives up. This does not guarantee recovery from persistent site errors.

6. Reliability, throughput, and cost

• Bound concurrency: The multiple endpoint allows up to 10 URLs and 10 instances in one call. For larger work, submit a batch rather than trying to put an unbounded URL list into one request.
• Handle asynchronous completion: Poll status and download only after completion. Use a bounded polling interval and stop or report the job when it reaches an error state.
• Use cache when appropriate: Reusing a recent capture can avoid repeating work for the same URL and instance; use cache=0 when the screenshot must reflect the latest page.
• Expect target-site variability: Redirects, slow pages, access restrictions, and temporary outages can affect individual captures. Track results per URL instead of treating a partially successful list as wholly successful.
• Check account requirements and price: The Browshot documentation states that requests to private and shared instances require a positive balance. Pricing and account-specific balance requirements are not established here; check your current account and Browshot’s pricing information before estimating a batch cost.

7. Common problems and fixes

Symptom	Likely cause	Fix
Request rejected or invalid	Bad API key, malformed URL, invalid parameter, or unsupported instance	Read the response and error header, verify the key and absolute URL, and confirm accepted parameters and instance access in the API reference.
More than 10 URLs or instances submitted	The multiple endpoint limit was exceeded	Split the work into compliant requests or use the batch upload workflow for a large list.
Response indicates queued or processing	Capture is asynchronous	Retain the screenshot ID, check its status, and retrieve the image after it finishes.
Screenshot shows incomplete content	Page scripts or delayed content were not ready at capture time	Use a suitable post-load delay and compare screen with page if the needed content is below the viewport.
Stale image returned	A recent cached screenshot was reused	Set cache=0 when you need a fresh capture.
One or more batch URLs failed	Target page was unavailable or persistently errored	Inspect the failed entries, retry only after confirming the target is reachable, and account for the documented limited retries on temporary failures.
Batch upload rejected	Wrong multipart field, missing instance ID, or malformed file	Use the current batch API reference for multipart field names; ensure the file has one URL per line and include the required instance ID.
Unable to request private or shared instance captures	Account balance requirement is not met	Check the current account balance and instance requirements.

Or skip the browser setup

ScreenshotNeo accepts a URL in one GET request and returns an image or PDF. For example, capture a page as WebP:

ScreenshotNeo API documentation

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo can remove cookie banners, popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up for ScreenshotNeo’s free plan.

FAQ

Can I capture more than one screenshot per URL?

Yes. The multiple endpoint accepts several instance IDs as well as several URLs, up to 10 of each per call.

Does batch input support CSV?

The documented input is a text file with one URL per line. Treat it as a newline-delimited list unless Browshot’s current batch reference says otherwise.

Does a batch finish immediately?

Not necessarily. Screenshot requests can be queued or processed asynchronously. Check status and retrieve the output when complete.

Does cache apply across different browser instances?

The documented cache match is for the same URL and instance. A different instance should be treated as a distinct capture.