PHP API Reference

Complete API reference for the Browser7 PHP SDK.

---

Browser7Client

The main class for interacting with the Browser7 API.

Constructor

new Browser7Client($apiKey, $baseUrl)

Creates a new Browser7 client.

Parameters:

• $apiKey (string, required) - Your Browser7 API key from the Dashboard
• $baseUrl (string|null, optional) - Full API base URL including version path. Defaults to 'https://api.browser7.com/v1'

Returns: Browser7Client

Example:

use Browser7\Browser7Client;

// Default (production)
$client = new Browser7Client('b7_your_api_key_here');

// Custom regional endpoint
$client = new Browser7Client(
    'b7_your_api_key_here',
    'https://ca-api.browser7.com/v1'
);

Throws:

• Browser7Error - If $apiKey is empty

---

Methods

render($url, $options)

Render a URL and automatically poll for the result. This is the recommended method for most use cases.

Parameters:

• $url (string, required) - The URL to render
• $options (array, optional) - Render options (see table below)

Options:

Key	Type	Description	Default
countryCode	string	Country code (e.g., 'US', 'GB', 'DE')	Auto-select
city	string	City name (e.g., 'new.york', 'london')	Auto-select
waitFor	array	Array of wait actions, max 10 (use WaitAction::* helpers)	[]
captcha	string	CAPTCHA mode: 'disabled', 'auto', 'recaptcha_v2', 'recaptcha_v3', 'turnstile'	'disabled'
blockImages	bool	Block images for faster rendering	true
fetchUrls	array	Additional URLs to fetch after render (max 10)	[]
includeScreenshot	bool	Enable screenshot capture	false
screenshotFormat	string	Screenshot format: 'jpeg' or 'png'	'jpeg'
screenshotQuality	int	JPEG quality 1–100 (JPEG only)	80
screenshotFullPage	bool	Capture full page or viewport only	false
debug	bool	Enable debug mode: syncs HTML, fetch responses, and screenshots to dashboard for 7 days	false
onProgress	callable	Progress callback function	null

Returns: RenderResult

Example:

use Browser7\WaitAction;

$result = $client->render('https://example.com', [
    'countryCode' => 'US',
    'city'        => 'new.york',
    'waitFor'     => [
        WaitAction::click('.cookie-accept'),
        WaitAction::selector('.main-content', 'visible'),
    ],
    'blockImages' => true,
    'onProgress'  => function (array $event) {
        echo "[{$event['type']}] " . ($event['status'] ?? '') . PHP_EOL;
    }
]);

Progress Callback:

The onProgress callable receives an associative array:

[
    'type'       => 'started' | 'polling' | 'completed' | 'failed',
    'renderId'   => 'ren_abc123',
    'timestamp'  => '2026-03-09T12:00:00+00:00',   // ISO 8601
    'status'     => 'processing',                   // polling events only
    'attempt'    => 3,                              // polling events only
    'retryAfter' => 1                               // polling events only
]

Throws:

• AuthenticationError - Invalid or missing API key (401, 403)
• ValidationError - Invalid parameters (400)
• RateLimitError - Too many concurrent requests (429)
• InsufficientBalanceError - Insufficient account balance (402)
• RenderError - Render failed or timed out
• Browser7Error - Network errors or other failures

---

createRender($url, $options)

Create a render job without polling (low-level API).

Use this when you need manual control over polling. For most use cases, prefer render().

Parameters:

• $url (string, required) - The URL to render
• $options (array, optional) - Same options as render(), excluding onProgress

Returns: array with renderId

['renderId' => 'ren_abc123']

Example:

$response = $client->createRender('https://example.com', [
    'countryCode' => 'US'
]);
$renderId = $response['renderId'];
// Poll manually with getRender($renderId)

Throws:

• AuthenticationError - Invalid or missing API key (401, 403)
• ValidationError - Invalid parameters (400)
• RateLimitError - Too many concurrent requests (429)
• InsufficientBalanceError - Insufficient account balance (402)
• Browser7Error - Network errors or other failures

---

getRender($renderId)

Get the status and result of a render job (low-level API).

Parameters:

• $renderId (string, required) - The render ID from createRender()

Returns: RenderResult

Example:

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

sleep(2);

while (true) {
    $result = $client->getRender($renderId);

    if ($result->status === 'completed') {
        echo $result->html;
        break;
    } elseif ($result->status === 'failed') {
        throw new \RuntimeException('Render failed: ' . $result->error);
    }

    sleep($result->retryAfter);
}

Throws:

• AuthenticationError - Invalid or missing API key (401, 403)
• RenderError - Render failed or timed out
• Browser7Error - Network errors or other failures

---

getAccountBalance()

Get the current account balance.

Parameters: None

Returns: AccountBalance

Example:

$balance = $client->getAccountBalance();

echo "Total: {$balance->totalBalanceFormatted}" . PHP_EOL;
echo "Renders remaining: {$balance->totalBalanceCents}" . PHP_EOL;
echo "Paid: {$balance->breakdown->paid->formatted}" . PHP_EOL;
echo "Free: {$balance->breakdown->free->formatted}" . PHP_EOL;
echo "Bonus: {$balance->breakdown->bonus->formatted}" . PHP_EOL;

Throws:

• AuthenticationError - Invalid or missing API key (401, 403)
• Browser7Error - Network errors or other failures

---

getRegions()

Get available API regions. Useful for validating region codes or building region-selection UIs.

This is a public endpoint - no API key is required, but the SDK makes the call for you with a consistent interface.

Parameters: None

Returns: Region[]

Example:

$regions = $client->getRegions();

foreach ($regions as $region) {
    if ($region->status === 'active') {
        echo "{$region->code}: {$region->name}" . PHP_EOL;
    }
}

Throws:

• Browser7Error - Network errors or other failures

---

WaitAction

Static helper class for creating wait action arrays.

WaitAction::delay($duration)

Create a delay wait action.

Parameters:

• $duration (int, required) - Duration in milliseconds (100–60000)

Example:

use Browser7\WaitAction;

$action = WaitAction::delay(3000);
// ['type' => 'delay', 'duration' => 3000]

---

WaitAction::selector($selector, $state, $timeout)

Create a selector wait action to wait for a DOM element.

Parameters:

• $selector (string, required) - CSS selector
• $state (string, optional) - Element state: 'visible', 'hidden', or 'attached'. Default: 'visible'
• $timeout (int, optional) - Timeout in milliseconds (1000–60000). Default: 30000

Example:

$action = WaitAction::selector('.main-content', 'visible', 10000);

---

WaitAction::text($text, $selector, $timeout)

Create a text wait action to wait for specific text content.

Parameters:

• $text (string, required) - Text to wait for
• $selector (string|null, optional) - CSS selector to limit search scope
• $timeout (int, optional) - Timeout in milliseconds (1000–60000). Default: 30000

Example:

$action = WaitAction::text('In Stock', '.availability', 10000);

---

WaitAction::click($selector, $timeout)

Create a click wait action to click an element (e.g., dismiss cookie banners).

Parameters:

• $selector (string, required) - CSS selector of element to click
• $timeout (int, optional) - Timeout in milliseconds (1000–60000). Default: 30000

Example:

$action = WaitAction::click('.cookie-accept', 5000);

---

Type Definitions

RenderResult

The result returned by render() and getRender().

$result->status           // string: 'completed', 'processing', or 'failed'
$result->html             // string|null: Rendered HTML (automatically decompressed)
$result->screenshot       // string|null: Base64-encoded image (if includeScreenshot was true)
$result->loadStrategy     // string|null: Load strategy used
$result->selectedCity     // array|null: City used for rendering (see below)
$result->bandwidthMetrics // array|null: Network bandwidth statistics (see below)
$result->captcha          // array|null: CAPTCHA detection and handling info (see below)
$result->timingBreakdown  // array|null: Performance timing breakdown in ms
$result->fetchResponses   // array|null: Fetch responses (if fetchUrls provided, decompressed)
$result->retryAfter       // int: Server-suggested retry interval in seconds
$result->error            // string|null: Error message if status is 'failed'

selectedCity:

$result->selectedCity = [
    'name'        => 'new.york',
    'displayName' => 'New York',
    'latitude'    => 40.7128,
    'longitude'   => -74.0060,
    'timezoneId'  => 'America/New_York'
];

bandwidthMetrics:

$result->bandwidthMetrics = [
    'networkBytes' => 1024000,
    'cachedBytes'  => 204800,
    'cacheHitRate' => '16.7%'
];

captcha:

$result->captcha = [
    'detected' => true,
    'handled'  => true,
    'sitekey'  => '6Le-...'  // Present if CAPTCHA was detected
];

---

AccountBalance

$balance->totalBalanceCents     // int: Total balance in cents (1 cent = 1 render)
$balance->totalBalanceFormatted // string: e.g., '$13.00'
$balance->breakdown->paid->cents      // int
$balance->breakdown->paid->formatted  // string
$balance->breakdown->free->cents      // int
$balance->breakdown->free->formatted  // string
$balance->breakdown->bonus->cents     // int
$balance->breakdown->bonus->formatted // string

---

Region

$region->code    // string: e.g., 'eu', 'ca', 'sg'
$region->name    // string: e.g., 'Europe'
$region->status  // string: 'active', 'maintenance', or 'inactive'

---

Supported Countries

AT, BE, CA, CH, CZ, DE, FR, GB, HR, HU, IT, NL, PL, SK, US

See the Geo-Targeting Guide for available cities within each country.

---

Error Classes

The SDK provides typed exception classes for programmatic error handling. All exception classes extend \RuntimeException.

Import

use Browser7\Browser7Error;
use Browser7\AuthenticationError;
use Browser7\ValidationError;
use Browser7\RateLimitError;
use Browser7\InsufficientBalanceError;
use Browser7\RenderError;

Hierarchy

Class	HTTP Status	Methods
Browser7Error	Network errors, 404, 500+	getHttpStatusCode(), getResponseBody()
AuthenticationError	401, 403	(inherits base)
ValidationError	400	getDetails()
RateLimitError	429	getConcurrentLimit()
InsufficientBalanceError	402	(inherits base)
RenderError	422, render failures	getErrorCode(), getRenderId(), getBillable()

Usage

try {
    $result = $client->render('https://example.com');
} catch (AuthenticationError $e) {
    echo 'Check your API key';
} catch (ValidationError $e) {
    echo 'Invalid parameters: ' . json_encode($e->getDetails());
} catch (RateLimitError $e) {
    echo 'Rate limited (max: ' . $e->getConcurrentLimit() . ')';
} catch (InsufficientBalanceError $e) {
    echo 'Top up your account';
} catch (RenderError $e) {
    echo 'Render failed: ' . $e->getErrorCode() . ', billable: ' . ($e->getBillable() ? 'yes' : 'no');
} catch (Browser7Error $e) {
    echo 'Other error: ' . $e->getMessage();
}

All exception classes extend Browser7Error, which extends \RuntimeException. Existing catch (\RuntimeException $e) blocks will still catch all SDK errors.

---

Next Steps

• Examples - Copy-paste ready examples for common use cases
• Quick Start - Basics and feature overview
• Advanced API - Direct REST API usage