> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nativeport.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nativeport.ai/_mcp/server.

# ScraperAPI

Fronts the synchronous endpoint of [ScraperAPI](https://scraperapi.com); the gateway fills in the secret `api_key` parameter on the query string.

```
GET|POST|PUT /scraperapi   → https://api.scraperapi.com/?api_key=<secret>&<your query>
```

* `GET` retrieves the page at `url`.
* A `POST` or `PUT` delivers a form or body to the target, with the body relayed as-is.

Everything is driven by the **query string**: the target `url` plus any ScraperAPI parameter (`country_code`, `render`, `device_type`, `premium`, …). What you put there reaches ScraperAPI exactly as written.

## Credential handling

* **`api_key` goes in ahead of everything you send** — ScraperAPI wants its parameters placed before `url`, and this also keeps a target URL with incomplete encoding from swallowing them.
* **An `api_key` supplied by the client in the query is discarded** (any encoding), so nothing can displace the injected key.
* **The header form of the key, `x-sapi-api_key`, is discarded.**
* **`Authorization` is removed**, and here that matters beyond hygiene: under `keep_headers=true` ScraperAPI passes your headers on to the *scraped site* — a surviving gateway token would therefore leak to a third party.

Every other header — the `x-sapi-*` controls such as `x-sapi-render` included — goes through untouched.

## Examples

#### Basic scrape

```bash
curl "$GATEWAY/scraperapi?url=https://example.com" \
  -H "Authorization: Bearer $TOKEN"
```

#### Render JS + geotarget

```bash
curl "$GATEWAY/scraperapi?url=https://example.com&render=true&country_code=us" \
  -H "Authorization: Bearer $TOKEN"
```

#### POST a form to the target

```bash
curl -X POST "$GATEWAY/scraperapi?url=https://example.com/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field": "value"}'
```

Expect slow scrapes — **\~70 seconds** is the allowance ScraperAPI suggests. Since the gateway simply waits on the upstream, the timeout that actually binds is your client's. Payloads can be big too (up to \~50MB on ScraperAPI's side), and the gateway streams every byte back.

ScraperAPI's response comes back untouched. Every supported parameter is listed in [ScraperAPI's documentation](https://docs.scraperapi.com).