POST /batch/create — Documentation API

← Retour à l’index API

POST /batch/create

Create batch screenshot job

Options

Les options sont regroupées pour faciliter la lecture, sur le modèle d’une documentation centrée sur les paramètres.

Essential

`browser`

body enum(chrome, firefox, brave) Facultatif

Exemple : chrome

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

`country`

body string Facultatif

Exemple : 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 Facultatif

Exemple : 5

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

`hide_ads`

body boolean Facultatif

Exemple : false

Aucune description dans la spécification OpenAPI.

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 Facultatif

Exemple : false

Aucune description dans la spécification OpenAPI.

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

`screen_height`

body integer Facultatif

Exemple : 1280

Aucune description dans la spécification OpenAPI.

`screen_width`

body integer Facultatif

Exemple : 1024

Aucune description dans la spécification OpenAPI.

`size`

body enum(screen, page) Facultatif

Exemple : screen

Aucune description dans la spécification OpenAPI.

Request

`cookie`

body string Facultatif

Aucune description dans la spécification OpenAPI.

`header`

body string Facultatif

Custom HTTP header(s)

`post_data`

body string Facultatif

Aucune description dans la spécification OpenAPI.

`referer`

body string Facultatif

Aucune description dans la spécification OpenAPI.

Browser

`dark`

body boolean Facultatif

Exemple : false

Aucune description dans la spécification OpenAPI.

`strict_ssl`

body boolean Facultatif

Exemple : true

Aucune description dans la spécification OpenAPI.

Automation

`steps`

body string Facultatif

JSON-encoded steps array

Screenshot

`cache`

body integer Facultatif

Exemple : 86400

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

`shot_interval`

body integer Facultatif

Exemple : 0

Aucune description dans la spécification OpenAPI.

`shots`

body integer Facultatif

Exemple : 1

Aucune description dans la spécification OpenAPI.

`target`

body string Facultatif

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[] Facultatif

App configuration IDs to run after each screenshot is finished

`file`

body string Obligatoire

Text file with one URL per line

`filename_template`

body string Facultatif

Exemple : {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) Facultatif

Exemple : s3

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

`hosting_bucket`

body string Facultatif

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

`hosting_private`

body boolean Facultatif

Exemple : false

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

`Idempotency-Key`

header string Facultatif

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

`name`

body string Facultatif

Batch name for reference

`thumbnail_bottom`

body integer Facultatif

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

`thumbnail_format`

body enum(png, jpeg, webp) Facultatif

Exemple : png

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

`thumbnail_height`

body integer Facultatif

Thumbnail target height in pixels.

`thumbnail_left`

body integer Facultatif

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

`thumbnail_quality`

body integer Facultatif

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

`thumbnail_ratio`

body enum(fit, fill) Facultatif

Exemple : fit

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

`thumbnail_right`

body integer Facultatif

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

`thumbnail_scale`

body number Facultatif

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

`thumbnail_top`

body integer Facultatif

Crop box top edge (px).

`thumbnail_width`

body integer Facultatif

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 Facultatif

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

Output & Format

`html`

body boolean Facultatif

Exemple : false

Aucune description dans la spécification OpenAPI.

Geolocation

`geo_enable`

body boolean Facultatif

Exemple : false

Enable geolocation emulation

`geo_latitude`

body number Facultatif

Override latitude for geolocation

`geo_longitude`

body number Facultatif

Override longitude for geolocation

`language`

body string Facultatif

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

`timezone`

body string Facultatif

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

Device

`device_landscape`

body boolean Facultatif

Use landscape orientation

`device_mobile`

body boolean Facultatif

Enable mobile emulation

`device_name`

body string Facultatif

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

`device_scale`

body number Facultatif

Device scale factor

`device_touch`

body boolean Facultatif

Enable touch input

PDF Options

`pdf`

body boolean Facultatif

Exemple : false

Aucune description dans la spécification OpenAPI.

`pdf_background`

body boolean Facultatif

Exemple : false

Aucune description dans la spécification OpenAPI.

`pdf_format`

body enum(a4, letter, legal) Facultatif

Exemple : letter

Aucune description dans la spécification OpenAPI.

`pdf_landscape`

body boolean Facultatif

Exemple : false

Aucune description dans la spécification OpenAPI.

`pdf_margin`

body string Facultatif

Exemple : 0px

Aucune description dans la spécification OpenAPI.

`pdf_margin_bottom`

body string Facultatif

Exemple : 0px

Aucune description dans la spécification OpenAPI.

`pdf_margin_left`

body string Facultatif

Exemple : 0px

Aucune description dans la spécification OpenAPI.

`pdf_margin_right`

body string Facultatif

Exemple : 0px

Aucune description dans la spécification OpenAPI.

`pdf_margin_top`

body string Facultatif

Exemple : 0px

Aucune description dans la spécification OpenAPI.

`pdf_one_page`

body boolean Facultatif

Exemple : false

Aucune description dans la spécification OpenAPI.

Réponses

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"
  }
}

Options

Essential

browser

country

delay

hide_ads

hide_popups

screen_height

screen_width

size

Request

cookie

header

post_data

referer

Page

max_wait

script

trackers

Browser

dark

strict_ssl

Automation

steps

Screenshot

cache

shot_interval

shots

target

App

apps

file

filename_template

hosting

hosting_bucket

hosting_private

Idempotency-Key

name

thumbnail_bottom

thumbnail_format

thumbnail_height

thumbnail_left

thumbnail_quality

thumbnail_ratio

thumbnail_right

thumbnail_scale

thumbnail_top

thumbnail_width

thumbnail_zoom

Output & Format

html

Geolocation

geo_enable

geo_latitude

geo_longitude

language

timezone

Device

device_landscape

device_mobile

device_name

device_scale

device_touch

PDF Options

pdf

pdf_background

pdf_format

pdf_landscape

pdf_margin

pdf_margin_bottom

pdf_margin_left

pdf_margin_right

pdf_margin_top

pdf_one_page

Réponses

`browser`

`country`

`delay`

`hide_ads`

`hide_popups`

`screen_height`

`screen_width`

`size`

`cookie`

`header`

`post_data`

`referer`

`max_wait`

`script`

`trackers`

`dark`

`strict_ssl`

`steps`

`cache`

`shot_interval`

`shots`

`target`

`apps`

`file`

`filename_template`

`hosting`

`hosting_bucket`

`hosting_private`

`Idempotency-Key`

`name`

`thumbnail_bottom`

`thumbnail_format`

`thumbnail_height`

`thumbnail_left`

`thumbnail_quality`

`thumbnail_ratio`

`thumbnail_right`

`thumbnail_scale`

`thumbnail_top`

`thumbnail_width`

`thumbnail_zoom`

`html`

`geo_enable`

`geo_latitude`

`geo_longitude`

`language`

`timezone`

`device_landscape`

`device_mobile`

`device_name`

`device_scale`

`device_touch`

`pdf`

`pdf_background`

`pdf_format`

`pdf_landscape`

`pdf_margin`

`pdf_margin_bottom`

`pdf_margin_left`

`pdf_margin_right`

`pdf_margin_top`

`pdf_one_page`