Create Render

Create a new render job to scrape and render a webpage.

Endpoint

POST /v1/renders

Request

Headers

Header	Required	Description
`Authorization`	Yes	Bearer token with your API key
`Content-Type`	Yes	Must be `application/json`

Body Parameters

Parameter	Type	Required	Description
`url`	string	Yes	The URL to render (must include protocol: http:// or https://)
`countryCode`	string	No	ISO 3166-1 alpha-2 country code for geo-targeting (e.g., `US`, `GB`, `DE`)
`city`	string	No	City name for more specific geo-targeting (e.g., `new.york`, `london`)
`waitFor`	array	No	Array of wait actions to execute before capturing (max 10)
`captcha`	string	No	CAPTCHA handling mode. Default: `disabled`
`blockImages`	boolean	No	Whether to block image loading for faster renders. Default: `true`
`fetchUrls`	array	No	Additional URLs to fetch after rendering (max 10)
`includeScreenshot`	boolean	No	Enable screenshot capture in the response. Default: `false`
`screenshotFormat`	string	No	Screenshot format: `jpeg` or `png`. Default: `jpeg`
`screenshotQuality`	number	No	JPEG quality 1-100 (only applies to JPEG format). Default: `80`
`screenshotFullPage`	boolean	No	Capture full scrollable page instead of viewport only. Default: `false`
`debug`	boolean	No	Enable debug mode: syncs HTML, fetch responses, and screenshots to the dashboard for 7 days. Default: `false`
`forceNewProxy`	boolean	No	Force a new proxy session with a fresh IP address instead of reusing an existing session for this domain. Default: `false`

Wait Actions

The waitFor parameter accepts an array of action objects that execute sequentially before capturing the page HTML. Maximum 10 actions per render.

Delay Action

Wait for a fixed duration:

{
  "type": "delay",
  "duration": 3000
}

Field	Type	Required	Description
`type`	string	Yes	Must be `"delay"`
`duration`	number	Yes	Milliseconds to wait (100-60000)

Selector Action

Wait for an element to reach a specific state:

{
  "type": "selector",
  "selector": ".product-price",
  "state": "visible",
  "timeout": 10000
}

Field	Type	Required	Description
`type`	string	Yes	Must be `"selector"`
`selector`	string	Yes	CSS selector to wait for
`state`	string	No	Element state: `visible`, `hidden`, or `attached`. Default: `visible`
`timeout`	number	No	Max wait time in milliseconds (1000-60000). Default: 30000

Text Action

Wait for specific text to appear on the page:

{
  "type": "text",
  "text": "In Stock",
  "selector": ".availability",
  "timeout": 10000
}

Field	Type	Required	Description
`type`	string	Yes	Must be `"text"`
`text`	string	Yes	Text content to wait for
`selector`	string	No	CSS selector to limit search scope
`timeout`	number	No	Max wait time in milliseconds (1000-60000). Default: 30000

Click Action

Click an element and wait for navigation/changes:

{
  "type": "click",
  "selector": "#load-more-btn",
  "timeout": 5000
}

Field	Type	Required	Description
`type`	string	Yes	Must be `"click"`
`selector`	string	Yes	CSS selector of element to click
`timeout`	number	No	Max wait time in milliseconds (1000-60000). Default: 30000

CAPTCHA Modes

Mode	Description
`disabled`	No CAPTCHA handling (default)
`auto`	Automatically detect and solve any supported CAPTCHA type
`recaptcha_v2`	Specifically handle reCAPTCHA v2
`recaptcha_v3`	Specifically handle reCAPTCHA v3
`turnstile`	Specifically handle Cloudflare Turnstile

Screenshots

Enable screenshot capture by setting includeScreenshot to true. Screenshots are taken after all wait actions have completed.

Formats

Format	Best for	Notes
`jpeg`	Most use cases	Smaller file size, configurable quality. Default format
`png`	Pixel-perfect accuracy	Lossless, larger file size. Best for visual regression testing

Quality (JPEG only)

The screenshotQuality parameter controls JPEG compression (1-100). Higher values produce larger, sharper images:

Quality	Typical use
10-30	Quick visual checks, smallest file size
80	Good balance of quality and size (default)
100	Maximum quality, largest file size

This parameter is ignored when screenshotFormat is png.

Full Page vs Viewport

Mode	Captures	Use case
`screenshotFullPage: false`	Visible viewport only (default)	Above-the-fold content, consistent dimensions
`screenshotFullPage: true`	Entire scrollable page	Full page archival, long-form content

Example

{
  "url": "https://example.com",
  "includeScreenshot": true,
  "screenshotFormat": "png",
  "screenshotFullPage": true
}

The screenshot is returned as a base64-encoded string in the screenshot field of the render result.

Response

Success Response (201 Created)

{
  "renderId": "ren_abc123xyz"
}

Field	Type	Description
`renderId`	string	Unique identifier for this render job. Use with GET /renders/:id

Error Responses

See Error Handling for detailed error responses.

Examples

Basic Render

Render a page with default settings:

curl -X POST https://api.browser7.com/v1/renders \
  -H "Authorization: Bearer b7_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com"
  }'

Geo-Targeted Render

Render from a specific country:

curl -X POST https://api.browser7.com/v1/renders \
  -H "Authorization: Bearer b7_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "countryCode": "GB"
  }'

City-Specific Render

Render from a specific city:

curl -X POST https://api.browser7.com/v1/renders \
  -H "Authorization: Bearer b7_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "countryCode": "US",
    "city": "new.york"
  }'

Render with Wait Actions

Wait for dynamic content to load:

curl -X POST https://api.browser7.com/v1/renders \
  -H "Authorization: Bearer b7_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "waitFor": [
      {
        "type": "selector",
        "selector": ".product-list",
        "state": "visible",
        "timeout": 10000
      },
      {
        "type": "delay",
        "duration": 2000
      }
    ]
  }'

Render with CAPTCHA Solving

Automatically solve CAPTCHAs:

curl -X POST https://api.browser7.com/v1/renders \
  -H "Authorization: Bearer b7_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/protected",
    "captcha": "auto"
  }'

Advanced Example

Combine multiple features:

curl -X POST https://api.browser7.com/v1/renders \
  -H "Authorization: Bearer b7_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/store",
    "countryCode": "US",
    "city": "new.york",
    "captcha": "auto",
    "blockImages": false,
    "waitFor": [
      {
        "type": "click",
        "selector": "#cookie-accept",
        "timeout": 5000
      },
      {
        "type": "selector",
        "selector": ".product-grid",
        "state": "visible",
        "timeout": 10000
      }
    ],
    "fetchUrls": [
      "https://example.com/api/prices",
      "https://example.com/api/inventory"
    ]
  }'

SDK Examples

The SDKs provide convenient methods and helper functions for creating renders:

Node.js

const Browser7 = require('browser7');
const client = new Browser7({ apiKey: 'b7_your_api_key' });

// Basic render
const { renderId } = await client.createRender('https://example.com');

// With options
const { renderId } = await client.createRender('https://example.com', {
  countryCode: 'US',
  city: 'new.york',
  captcha: 'auto',
  waitFor: [
    Browser7.waitForSelector('.content', 'visible', 10000),
    Browser7.waitForDelay(2000)
  ]
});

Python

from browser7 import Browser7, wait_for_selector, wait_for_delay

client = Browser7(api_key='b7_your_api_key')

# Basic render
response = client.create_render('https://example.com')
render_id = response['renderId']

# With options
response = client.create_render(
    'https://example.com',
    country_code='US',
    city='new.york',
    captcha='auto',
    wait_for=[
        wait_for_selector('.content', state='visible', timeout=10000),
        wait_for_delay(2000)
    ]
)

PHP

use Browser7\Browser7Client;
use Browser7\WaitAction;

$client = new Browser7Client('b7_your_api_key');

// Basic render
$response = $client->createRender('https://example.com');
$renderId = $response['renderId'];

// With options
$response = $client->createRender('https://example.com', [
    'countryCode' => 'US',
    'city' => 'new.york',
    'captcha' => 'auto',
    'waitFor' => [
        WaitAction::selector('.content', 'visible', 10000),
        WaitAction::delay(2000)
    ]
]);

Next Steps

After creating a render, poll for completion:

Wait 2-3 seconds for processing to begin
GET /renders/:id to check status
Continue polling until status is completed or failed
Use the retryAfter field to optimize polling interval

Or use the SDK's render() method which handles polling automatically:

// Node.js - handles creation + polling automatically
const result = await client.render('https://example.com', {
  countryCode: 'US'
});
console.log(result.html);

Get Render - Retrieve render results
Wait Actions Guide - Detailed guide on wait actions
Geo-Targeting Guide - Country and city selection
CAPTCHA Solving Guide - CAPTCHA handling strategies

Endpoint​

Request​

Headers​

Body Parameters​

Wait Actions​

Delay Action​

Selector Action​

Text Action​

Click Action​

CAPTCHA Modes​

Screenshots​

Formats​

Quality (JPEG only)​

Full Page vs Viewport​

Example​

Response​

Success Response (201 Created)​

Error Responses​

Examples​

Basic Render​

Geo-Targeted Render​

City-Specific Render​

Render with Wait Actions​

Render with CAPTCHA Solving​

Advanced Example​

SDK Examples​

Node.js​

Python​

PHP​

Next Steps​

Related Documentation​