Parameters

The Scraper API offers comprehensive control through a rich set of parameters. This reference covers all available options organized by category.

Core Parameters

Scraping Modes

request - Fast HTTP request without JavaScript

• Best for static sites (blogs, news, documentation)
• Lowest cost (1× multiplier)
• Timeout: 30 seconds

browser - Full browser with JavaScript rendering

• Best for SPAs (React, Vue, Angular)
• Supports screenshots and JavaScript automation
• Higher cost (5× multiplier)
• Timeout: 45 seconds

auto (default) - Intelligent detection

• Tries HTTP request first, upgrades to browser if needed
• Optimizes cost automatically
• Charges 50% of request cost + full browser cost when upgraded

Output Control

Content Formats

html - Raw HTML with absolute URLs markdown - Clean, readable text format (ideal for AI processing) screenshot - Full-page PNG image (requires mode=browser)

Proxy Configuration

Proxy Types Comparison

Session Management Example:

{
  "proxy_session_id": "cart123",
  "proxy_country": "US"
}

Use the same session ID across multiple requests to maintain the same IP address—perfect for login flows or shopping carts.

See Proxy Types for detailed information.

Browser Timing

Wait Until Options

Example:

{
  "mode": "browser",
  "wait_until": "networkidle",
  "wait_seconds": 3
}

Device Emulation

Device Characteristics

Performance Optimization

Blockable Resource Types

Block unnecessary resources to speed up scraping and reduce costs:

{
  "block_resources": ["image", "stylesheet", "font", "media"]
}

Available types: document, stylesheet, image, media, font, script, texttrack, xhr, fetch, eventsource, websocket, manifest

Custom Headers

Example:

{
  "additional_headers": {
    "Authorization": "Bearer token123",
    "Accept-Language": "en-US,en;q=0.9",
    "Custom-Header": "value"
  }
}

Common use cases: API authentication, language preferences, custom tracking headers.

Visual Capture

Screenshots are:

• Full-page PNG images (not just viewport)
• Stored in Cloudflare R2 for 30 days
• Accessible via screenshot_uri in response
• Cost: +1 credit

AI Enhancement

AI Model: Google Gemini 2.0 Flash
Cost: +10 credits (additive)

Example:

{
  "ai_enhance": true,
  "ai_source": "markdown",
  "ai_prompt": "Extract product name, price, and availability as JSON"
}

See AI Enhancement for detailed examples.

JavaScript Automation

Supported Actions:

• {"click": "selector"} - Click an element
• {"wait": milliseconds} - Wait for duration
• {"fill": ["selector", "value"]} - Fill form field
• {"wait_for": "selector"} - Wait for element to appear

Example:

{
  "js_instructions": [
    {"wait_for": "#search-input"},
    {"fill": ["#search-input", "web scraping"]},
    {"click": "#search-button"},
    {"wait": 2000}
  ]
}

See JavaScript Automation for comprehensive examples.

Parameter Combinations

Fast Static Scraping (1 credit)

{
  "url": "https://example.com",
  "mode": "request",
  "proxy_type": "datacenter"
}

JavaScript Site with Screenshot (6 credits)

{
  "url": "https://spa-website.com",
  "mode": "browser",
  "screenshot": true,
  "proxy_type": "datacenter",
  "wait_until": "networkidle"
}

AI-Powered Content Extraction (15 credits)

{
  "url": "https://news.site.com/article",
  "mode": "browser",
  "content": "markdown",
  "ai_enhance": true,
  "ai_source": "markdown",
  "ai_prompt": "Summarize in 3 bullet points",
  "proxy_type": "datacenter"
}

High-Success Residential Proxy (25 credits)

{
  "url": "https://protected-site.com",
  "mode": "browser",
  "proxy_type": "residential",
  "proxy_country": "US",
  "wait_until": "networkidle",
  "block_resources": ["image", "font"]
}

Parameter Validation

The API validates all parameters before processing. Common validation errors:

• Invalid URL: Must include http:// or https://
• Invalid mode: Must be request, browser, or auto
• Invalid proxy_country: Must be a 2-letter ISO code
• Invalid proxy_session_id: Must be 6-8 alphanumeric characters
• Screenshot without browser: screenshot=true requires mode=browser or mode=auto
• AI without source: ai_enhance=true requires ai_source

Validation errors return 422 Unprocessable Entity with details in the response.