Request Parameters

Complete reference for all ScrapingForge API request parameters including core options, advanced features, and extraction rules.

Configure your scraping requests with these parameters.

Core Parameters

Parameter	Default	Type	Description
`url`	-	`string`	Required. Target URL to scrape. Must be a valid HTTP/HTTPS URL. Cost: 1 credit (base).
`render_js`	`false`	`boolean`	Enable JavaScript rendering using headless Chrome. Essential for SPAs and dynamic content. Cost: +5-8 credits (Trial: 8, Growth+: 5).
`premium_proxy`	`false`	`boolean`	Use residential proxies from 195 countries. Harder to detect and block. Combine with `country` for geo-targeting. Cost: +15 credits.
`elite_proxy`	`false`	`boolean`	ISP-registered static residential proxies. Perfect for long sessions and account management. Cost: +50 credits.
`screenshot`	`false`	`boolean`	Capture a PNG screenshot. Requires `render_js: true`. Returns base64-encoded image. Cost: +2 credits.
`ai_query`	-	`string`	AI-powered data extraction using natural language queries. Example: `"Extract product name, price, and availability"`. Cost: +10 credits.

Example Request:

{
  "url": "https://example.com",
  "render_js": true,
  "premium_proxy": true,
  "country": "US"
}

Advanced Options

Parameter	Default	Type	Description
`custom_headers`	-	`object`	Set custom HTTP headers for the request. Headers must use `Spf-` prefix. Example: `{"Spf-User-Agent": "...", "Spf-Referer": "..."}`.
`cookies`	-	`array`	Set cookies for the request. Each cookie is an object with `name`, `value`, `domain`, etc.
`wait`	-	`number`	Wait X milliseconds after page load. Example: `3000` for 3 seconds.
`wait_for`	-	`string`	Wait for CSS selector to appear before returning content. Example: `".product-price"`.
`window_width`	`1920`	`number`	Set viewport width for rendering. Useful for mobile vs desktop layouts.
`window_height`	`1080`	`number`	Set viewport height for rendering.
`method`	`'GET'`	`string`	HTTP method. Supports `GET`, `POST`, `PUT`, `DELETE`, etc.
`request_body`	-	`string`	Request body for POST requests. Must be JSON string.
`country`	-	`string`	2-letter country code for geo-targeting. Requires `premium_proxy: true`. Example: `"US"`, `"GB"`, `"DE"`.

Example with Advanced Options:

{
  "url": "https://example.com",
  "render_js": true,
  "wait_for": ".product-price",
  "window_width": 375,
  "window_height": 812,
  "custom_headers": {
    "Spf-User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)"
  }
}

Extraction Rules

Define CSS selectors or XPath expressions to extract specific data from the page. Returns structured JSON.

Property	Type	Description
`extract_rules`	`object`	Object containing extraction rules. Each key is the field name, and the value defines how to extract it.

Rule Properties

Each extraction rule supports the following properties:

Property	Default	Type	Description
`selector`	-	`string`	Required. CSS selector or XPath expression to locate the element.
`type`	`'text'`	`'text' \| 'html' \| 'attr' \| 'list'`	Type of extraction. `text` extracts text content, `html` extracts HTML, `attr` extracts attribute value, `list` extracts multiple elements.
`attr`	-	`string`	Attribute name to extract when `type` is `'attr'`. Example: `"src"`, `"href"`, `"data-id"`.

Example with Extraction Rules:

{
  "url": "https://example.com/product",
  "extract_rules": {
    "title": {
      "selector": "h1.product-title",
      "type": "text"
    },
    "price": {
      "selector": ".price",
      "type": "text"
    },
    "images": {
      "selector": "img.product-img",
      "type": "list",
      "attr": "src"
    },
    "description": {
      "selector": ".description",
      "type": "html"
    }
  }
}

Response:

{
  "title": "Example Product",
  "price": "$29.99",
  "images": [
    "https://example.com/img1.jpg",
    "https://example.com/img2.jpg"
  ],
  "description": "<p>Product description HTML</p>"
}

Credit Costs

Feature	Cost
Base request	1 credit
JS rendering (Trial)	+8 credits
JS rendering (Growth+)	+5 credits
Premium proxy	+15 credits
Elite proxy	+50 credits
Screenshot	+2 credits
AI query	+10 credits

Complete Example

{
  "url": "https://example.com/product",
  "render_js": true,
  "premium_proxy": true,
  "country": "US",
  "screenshot": true,
  "wait_for": ".product-price",
  "custom_headers": {
    "Spf-User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
  },
  "extract_rules": {
    "title": {"selector": "h1", "type": "text"},
    "price": {"selector": ".price", "type": "text"},
    "images": {"selector": "img.product", "type": "list", "attr": "src"}
  }
}

Total cost: 1 + 5 + 15 + 2 = 23 credits

API Endpoints

Scraping Amazon Products