Skip to main content
See also the API reference for more detail.

​
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 accepts GET requests at https://‍/browser. Webpages can be localized with geotargeting parameters. They’re 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.
If a site you’re targeting remains blocked, even with different browsing params, let us know. We can usually help unblock any site within 48 hours.

​
Authentication

You can access the service by including your secret API token in an Authorization header: 
Authorization: Bearer [API token here]
Here’s an example request that uses the common Curl command: 
curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/browser'\
'?url=https://example.com/'
This endpoint autoscales; if you receive a 503 response, maintain traffic and expect errors to resolve within a few minutes.

​
Browsing parameters

Besides the geotargeting and scheduling params linked above, required and optional browsing 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:
KeyRequiredPremiumValue
url✅⬜The URL 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 (coming soon); 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
ip⬜⬜The type of IP address to browse from, residential, isp, or datacenter (planned); a random IP type is used by default
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 HTML format to output to, rendered or raw (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

​
Device emulation

The device param lets you fetch 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: 
curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/browser/devices'
The API will return JSON that contains an alphabetized array of device names: 
[
  "Blackberry PlayBook",
  "Blackberry PlayBook landscape",
  "BlackBerry Z30",
  "[Remaining device names here]"
]
Then, pass your device name of choice in to your browsing request: 
curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/browser'\
'?url=https://crackberry.com/'\
'&device=blackberry+playbook'

​
Sticky sessions

To reuse a browser session across requests, set a cookie named session: 
curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
-H 'Cookie: session=12345' \
'https://api.agentfirst.dev/browser'\
'?url=https://www.amazon.com/s?k=luggage'
The cookie value can be any unique identifier of up to 255 characters (regardless of character encoding) and will make best efforts to route calls in the same session to the same egress node for up to 12 minutes.

​
Response format

Pages are returned as rendered HTML or raw (unrendered) HTML.

​
Additional examples

​
Cachebusting

curl -H "Authorization: Bearer $AGENT_FIRST_TOKEN" \
'https://api.agentfirst.dev/browser'\
'?url=https://api.weather.gov/alerts'\
'&expiration=0'