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

No description in OpenAPI spec.

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

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.

name

body string Optional

Batch name for reference

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