> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinmassive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browsing

> Unblock difficult-to-crawl websites.

export const Autoscaling = () => {
  return <Warning>
      This endpoint autoscales; if you receive a <code>503</code> response, maintain traffic and
      expect errors to resolve within a couple minutes.
    </Warning>;
};

export const Reference = ({endpoint}) => {
  return <Info>
      See also the <Link href={`reference/${endpoint}`}>API reference</Link> for more detail.
    </Info>;
};

export const apiEndpoint = 'render.joinmassive.com';

export const emailAddress = 'support@joinmassive.com';

export const companyName = 'Massive';

<Reference endpoint="browser" />

## Service usage

**{companyName}'s** browser service navigates intelligently on your behalf, rendering JavaScript,
solving [captchas](https://www.ibm.com/topics/captcha), and retrying failed requests. The service
has a RESTful interface that accepts `GET` requests at
**https\://‍{apiEndpoint}/browser**.

Webpages can be localized with <Link href="geotargeting">geotargeting parameters</Link>. They're
retrieved in real time by default or optionally queued for <Link href="scheduling">subsequent
retrieval</Link>. Up to **3 minutes** is allotted per real-time API call to accommodate
captcha-solving, multiple retries, and other mitigations. <Link href="usage">Usage data</Link> is
published regularly.

<Tip>
  If a site you're targeting remains blocked, even with different browsing params, <a href={`mailto:${emailAddress}`}>let us know</a>. We can usually help unblock any site within **48
  hours**.
</Tip>

### Authentication

You can access the service by including your secret API token in an `Authorization` header:

```http theme={null}
Authorization: Bearer [API token here]
```

Here's an example request that uses the [common Curl command](https://curl.se/):

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/browser'\
'?url=https://example.com/'
```

<Autoscaling />

### Browsing parameters

Besides the [geotargeting and scheduling params linked above](#service-usage), required and optional
browsing params can be added in a
[standard query string](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL#parameters).
See <Link href="pricing">our rate card</Link> for the prices of premium params. The keys and values
**{companyName}** supports are as follows:

| Key          | Required | Premium | Value                                                                                                                                                                                                                                               |
| :----------- | :------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`        | ✅        | ⬜       | The URL of the page to browse; any unsafe characters require [URL encoding](https://developer.mozilla.org/en-US/docs/Glossary/Percent-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](#device-emulation) 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 |
| `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](#response-format)); `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\://‍{apiEndpoint}/browser/devices**:

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/browser/devices'
```

The API will return JSON that contains an alphabetized array of device names:

```json theme={null}
[
  "Blackberry PlayBook",
  "Blackberry PlayBook landscape",
  "BlackBerry Z30",
  "[Remaining device names here]"
]
```

Then, pass your device name of choice into your browsing request:

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/browser'\
'?url=https://crackberry.com/'\
'&device=blackberry+playbook'
```

### Sticky sessions

To reuse a browser session across requests, set a cookie named `session`:

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
-H 'Cookie: session=12345' \
'https://render.joinmassive.com/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 **{companyName}** 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, raw (unrendered) HTML, or Markdown optimized for LLM prompts.

## Additional examples

### Cachebusting

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/browser'\
'?url=https://api.weather.gov/alerts'\
'&expiration=0'
```