Skip to content
← Back to API index
POST /batch/create

Create batch screenshot job

Options

Options are grouped for easier scanning, similar to parameter-focused docs.

Essential

browser

body enum(chrome, firefox, brave) Optional

Example: chrome

Browser to use for screenshot (chrome, firefox, or brave)

country

body string Optional

Example: us

ISO country code. Defaults to "us" when omitted.

Two-letter country code for routing the browser through a target country. Use this when validating localization, legal notices, pricing, and geo-specific rendering.

delay

body integer Optional

Example: 5

Seconds waited after page load. Values above 30 are capped to 30.

hide_ads

body boolean Optional

Example: false

No description in OpenAPI spec.

Enable ad filtering for cleaner captures and visual diffs. On some browser targets, behavior may vary depending on native filtering support.

hide_popups

body boolean Optional

Example: false

No description in OpenAPI spec.

Attempt to hide cookie banners and popup overlays before capture so outputs focus on page content.

screen_height

body integer Optional

Example: 1280

No description in OpenAPI spec.

screen_width

body integer Optional

Example: 1024

No description in OpenAPI spec.

size

body enum(screen, page) Optional

Example: screen

No description in OpenAPI spec.

Request

cookie

body string Optional

No description in OpenAPI spec.

header

body string Optional

Custom HTTP header(s)

post_data

body string Optional

No description in OpenAPI spec.

referer

body string Optional

No description in OpenAPI spec.

Page

max_wait

body integer Optional

Example: 0

No description in OpenAPI spec.

script

body string Optional

No description in OpenAPI spec.

trackers

body string Optional

JSON-encoded trackers array

Browser

dark

body boolean Optional

Example: false

No description in OpenAPI spec.

strict_ssl

body boolean Optional

Example: true

No description in OpenAPI spec.

Automation

steps

body string Optional

JSON-encoded steps array

Screenshot

cache

body integer Optional

Example: 86400

Cache duration in seconds. Maximum 2592000 seconds (30 days)

shot_interval

body integer Optional

Example: 0

No description in OpenAPI spec.

shots

body integer Optional

Example: 1

No description in OpenAPI spec.

target

body string Optional

CSS selector to capture an element

CSS selector of the element to capture. If provided, capture is scoped to the matched element instead of the full viewport/page.

App

apps

body integer[] Optional

App configuration IDs to run after each screenshot is finished

file

body string Required

Text file with one URL per line

filename_template

body string Optional

Example: {domain}/{yyyy}{mm}{dd}-{id}.png

Template for output filenames inside the ZIP archive. Supports variables: {id}, {domain}, {shot}, {browser}, {country}, {yyyy}, {mm}, {dd}, {date}, {random}, {tags}, {url}. If {id} is absent, it is injected automatically to guarantee unique filenames. The filename column in the CSV/TSV file overrides this template per row.

hosting

body enum(s3) Optional

Example: s3

Upload each completed screenshot through the AWS S3 app. The batch ZIP is not uploaded.

hosting_bucket

body string Optional

S3 bucket that grants write access to Browshot's AWS account.

hosting_private

body boolean Optional

Example: false

Use bucket-owner-full-control instead of public-read for uploaded objects.

Idempotency-Key

header string Optional

Retry key. Reusing the same key for the same API user returns the original batch.

name

body string Optional

Batch name for reference

thumbnail_bottom

body integer Optional

Crop box bottom edge (px, exclusive). 0 extends to the image's bottom edge.

thumbnail_format

body enum(png, jpeg, webp) Optional

Example: png

Output image format. Omit to preserve each image's original format.

thumbnail_height

body integer Optional

Thumbnail target height in pixels.

thumbnail_left

body integer Optional

Crop box left edge (px). Crop is applied before resizing.

thumbnail_quality

body integer Optional

Encoder quality (1-100) for jpeg/webp thumbnails. Ignored for png.

thumbnail_ratio

body enum(fit, fill) Optional

Example: fit

fit = contain within width/height (default); fill = cover the box, cropping overflow.

thumbnail_right

body integer Optional

Crop box right edge (px, exclusive). 0 extends to the image's right edge.

thumbnail_scale

body number Optional

Multiplier applied to the thumbnail dimensions (combines with thumbnail_zoom).

thumbnail_top

body integer Optional

Crop box top edge (px).

thumbnail_width

body integer Optional

Resize the images stored in the ZIP archive. Setting any thumbnail_* option makes the ZIP contain resized/reformatted thumbnails instead of the full-resolution captures; leaving them all unset keeps the originals (default). Non-image outputs (PDF, video, HTML) are never thumbnailed. Target width in pixels.

thumbnail_zoom

body integer Optional

Zoom percentage (1-100) applied to the thumbnail dimensions.

Output & Format

html

body boolean Optional

Example: false

No description in OpenAPI spec.

Geolocation

geo_enable

body boolean Optional

Example: false

Enable geolocation emulation

geo_latitude

body number Optional

Override latitude for geolocation

geo_longitude

body number Optional

Override longitude for geolocation

language

body string Optional

Override language/locale (e.g., en-US)

timezone

body string Optional

Override timezone (e.g., America/New_York)

Device

device_landscape

body boolean Optional

Use landscape orientation

device_mobile

body boolean Optional

Enable mobile emulation

device_name

body string Optional

Device name to emulate (e.g., iphone_15_pro)

device_scale

body number Optional

Device scale factor

device_touch

body boolean Optional

Enable touch input

PDF Options

pdf

body boolean Optional

Example: false

No description in OpenAPI spec.

pdf_background

body boolean Optional

Example: false

No description in OpenAPI spec.

pdf_format

body enum(a4, letter, legal) Optional

Example: letter

No description in OpenAPI spec.

pdf_landscape

body boolean Optional

Example: false

No description in OpenAPI spec.

pdf_margin

body string Optional

Example: 0px

No description in OpenAPI spec.

pdf_margin_bottom

body string Optional

Example: 0px

No description in OpenAPI spec.

pdf_margin_left

body string Optional

Example: 0px

No description in OpenAPI spec.

pdf_margin_right

body string Optional

Example: 0px

No description in OpenAPI spec.

pdf_margin_top

body string Optional

Example: 0px

No description in OpenAPI spec.

pdf_one_page

body boolean Optional

Example: false

No description in OpenAPI spec.

Responses

200

Batch created

▾ 
{
  "success": true,
  "data": [
    {
      "id": 98765,
      "status": "processing",
      "count": 150,
      "processed": 0,
      "failed": 0,
      "error": ""
    }
  ]
}
400

Invalid request

▾ 
{
  "error": "Request validation failed",
  "code": "VALIDATION_ERROR",
  "fields": {
    "url": [
      "URL is required"
    ],
    "country": [
      "Country code must be ISO 3166-1 alpha-2"
    ]
  }
}
401

Unauthorized

▾ 
{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}
403

Insufficient balance

▾ 
{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}
413

File too large

▾ 
{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}
500

Server error

▾ 
{
  "success": false,
  "error": "Invalid API key",
  "code": "INVALID_API_KEY",
  "details": {
    "request_id": "req_123456"
  }
}