Service usage
‘s browser service navigates intelligently on your behalf, rendering JavaScript, solving captchas, and retrying failed requests. The service has a RESTful interface that acceptsGET requests at
https:///browser and a
Chrome DevTools Protocol (CDP) interface for controlling browser navigation
yourself that accepts WebSocket connections at wss:///browser.
Webpages can be localized with geotargeting parameters. Those
requested via REST are retrieved in real time by default or optionally queued for subsequent retrieval. Up to 3 minutes is allotted per real-time API
call to accommodate captcha-solving, multiple retries, and other mitigations. Usage data is published regularly.
Authentication
You can access the service by including your secret API token in anAuthorization header:
REST parameters
Besides the geotargeting and scheduling params linked above, required and optional REST params can be added in a standard query string. See our rate card for the prices of premium params. The keys and values supports are as follows:| Key | Required | Premium | Value |
|---|---|---|---|
url | ✅ | ⬜ | The URL of up to 2,047 characters of the page to browse; any unsafe characters require URL encoding |
difficulty | ⬜ | ✅ | The difficulty pool to attempt to access the URL from, low, medium, or high (planned); low is the default difficulty |
speed | ⬜ | ✅ | The speed to attempt to access the URL at, light, ridiculous, or ludicrous (planned), where ridiculous is 30 percent faster on average than light speed; light is the default speed |
device | ⬜ | ⬜ | The name as returned by the devices resource of the device to emulate browsing on (these names are case insensitive but must include form- or URL-encoded spaces and punctuation marks); device emulation is unused by default |
session | ⬜ | ⬜ | Any unique identifier of up to 255 characters (regardless of character encoding); will make best efforts to route calls in the same session to the same egress node for up to 12 minutes |
captcha | ⬜ | ⬜ | The intended resolution of any detected captcha, solved, ignored, or rejected, where rejected results in a 403 response; solved is the default captcha resolution |
readiness | ⬜ | ⬜ | The standard ready event to await before snapshotting browsed content, load or domcontentloaded; load is the default ready event |
delay | ⬜ | ⬜ | The number of supplemental seconds to delay before snapshotting browsed content, from .1 to 10 inclusive; no delay is used by default |
format | ⬜ | ⬜ | The format to output to, rendered, raw, or markdown (see the section below); rendered is the default format |
expiration | ⬜ | ⬜ | The age in days of when to consider cached content expired, where 0 disables caching; 1 is the default number of days before expiration |
callback | ⬜ | ⬜ | The encoded HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN of up to 2,047 characters to notify when the (prerequisite) asynchronous content has been retrieved; any SQS queue must grant sqs:SendMessage permission to the arn:aws:iam::180363035301:role/api-instance AWS principal |
CDP interaction
If your use case involves interacting with not just reading pages, you can connect Puppeteer, Playwright, or another CDP-compatible automation framework to the browser service:View Playwright sample
View Playwright sample
difficulty, device, and session:
browser.disconnect() (Puppeteer), browser.close() (Playwright), or the equivalent.
Protocol mixture
You can control costs by mixing REST requests and CDP use within a sticky browser session. E.g., you may want to prepare a page for interaction over REST then interact with the page over CDP:View REST-to-CDP sample
View REST-to-CDP sample
Device emulation
Thedevice param lets you browse device-specific content, rather than the default desktop content.
For a list of supported smartphone and tablet devices, make a request with your API token and no
params to https:///browser/devices:
Response format
Read-only pages are returned as rendered HTML, raw (unrendered) HTML, or Markdown optimized for LLM prompts.Additional examples
Cachebusting
End-to-end Playwright
View end-to-end sample
View end-to-end sample