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

Start a website crawl

Options

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

App

domain

body string Required

Example: example.com

Domain being crawled

key

query string Optional

API key (optional if using JWT bearer token)

API key used for authentication. Use either the `key` query parameter or `X-API-KEY` header.

max_urls

body integer Required

Example: 100

Maximum number of pages to screenshot

url

body string Required

Example: https://example.com

Starting URL for the crawl

Geolocation

country

body string Optional

Example: us

ISO country code for browser location

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

Responses

200

Crawl created

▾ 
{
  "success": true,
  "data": {
    "id": 12345,
    "status": "finished",
    "domain": "example.com",
    "start_url": "https://example.com",
    "max_urls": 100,
    "total_discovered": 87,
    "processed": 85,
    "failed": 2,
    "error": "",
    "created_at": "",
    "started": 0,
    "finished": 0,
    "screenshots": [
      {
        "id": 12345678,
        "status": "finished",
        "error": "Request timeout after 30 seconds",
        "url": "https://example.com",
        "country": "us",
        "final_url": "https://www.example.com",
        "final_urls": [
          ""
        ],
        "response_code": 200,
        "apps": [
          {
            "id": 0,
            "app_id": "",
            "type": "",
            "name": "",
            "status": "pending",
            "filename": "",
            "error": "",
            "output_url": "",
            "output_data": {},
            "updated_at": ""
          }
        ],
        "cost": 1,
        "size": "screen",
        "cache": 86400,
        "delay": 5,
        "screen_width": 1024,
        "screen_height": 1280,
        "priority": 2,
        "referer": "",
        "post_data": "",
        "cookie": "",
        "script": "",
        "header": "",
        "html": false,
        "pdf": false,
        "pdf_background": false,
        "pdf_one_page": false,
        "pdf_landscape": false,
        "pdf_format": "a4",
        "pdf_margin": "20px",
        "pdf_margin_top": "20px",
        "pdf_margin_bottom": "20px",
        "pdf_margin_left": "20px",
        "pdf_margin_right": "20px",
        "video": false,
        "video_format": "mp4",
        "video_quality": 0,
        "video_speed": 0,
        "video_duration": 0,
        "video_fps": 0,
        "video_colors": 0,
        "video_scale": 0,
        "max_wait": 0,
        "hide_popups": false,
        "hide_ads": false,
        "dark": false,
        "shots": 1,
        "shot_interval": 0,
        "strict_ssl": false,
        "target": "",
        "geo_enable": false,
        "geo_latitude": 0,
        "geo_longitude": 0,
        "region": "",
        "language": "",
        "timezone": "",
        "device_name": "",
        "device_scale": 0,
        "device_mobile": false,
        "device_touch": false,
        "device_landscape": false,
        "browser": "chrome",
        "user_agent": "",
        "created_at": "2026-02-01T10:30:00Z",
        "finished_at": "2026-02-01T10:30:05Z",
        "tag": [
          ""
        ],
        "steps": [
          {}
        ],
        "trackers": [
          {
            "id": "test",
            "name": "page title",
            "value": "document.title",
            "name_type": "string",
            "input": "",
            "value_type": "string",
            "selector": "",
            "return": [
              {
                "found": 1,
                "shot": 1,
                "value": "My Page Title",
                "name": "page title"
              }
            ]
          }
        ],
        "links": [
          "https://example.com/about",
          "https://example.com/contact",
          "https://example.com/blog"
        ]
      }
    ]
  }
}
400

Invalid request

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

Unauthorized

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