> For the complete documentation index, see [llms.txt](https://docs.iproyal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.iproyal.com/scraping-tools/web-scraper-api-beta/api.md).

# API

Reference for every Web Scraper API endpoint.

### Base URL

```
https://scrape.iproyal.com/v1
```

All requests use HTTPS. Request and response bodies are JSON.

### Authentication

Send your API token in the `Authorization` header of every request:

```
Authorization: Bearer <your_api_token>
```

You can find your token in the IPRoyal dashboard. To replace it, use [Token Regenerate](/scraping-tools/web-scraper-api-beta/api/token-regenerate.md).

### Endpoints

| Method | Endpoint                                                                               | Description                                           |
| ------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `GET`  | [`/v1/user`](/scraping-tools/web-scraper-api-beta/api/user.md)                         | Your credit balance and limits                        |
| `POST` | [`/v1/scrape`](/scraping-tools/web-scraper-api-beta/api/scraping.md)                   | Scrape a web page, Google search results, or an image |
| `POST` | [`/v1/token/regenerate`](/scraping-tools/web-scraper-api-beta/api/token-regenerate.md) | Replace your API token                                |
| `GET`  | [`/v1/usage`](/scraping-tools/web-scraper-api-beta/api/usage.md)                       | Usage totals for a date range or for all time         |
| `GET`  | [`/v1/usage/history`](/scraping-tools/web-scraper-api-beta/api/usage-history.md)       | Individual requests, newest first                     |

### Errors

Every error uses the same shape:

```json
{
  "error": {
    "code": "insufficient_credit",
    "message": "Not enough credit for this call."
  }
}
```

Branch your code on `error.code`. The `message` is meant for people and can change.

#### Error Codes

| HTTP Status    | `error.code`                 | Meaning                                                                   | What to Do                                                                                                           |
| -------------- | ---------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `400`          | `invalid_request`            | The request is not valid. The `message` names the problem.                | Fix the request. Do not retry it unchanged.                                                                          |
| `401`          | `invalid_token`              | The API token is missing or not recognized.                               | Check the `Authorization` header. After a token change, use the new token.                                           |
| `402`          | `insufficient_credit`        | Your credit balance is empty.                                             | Purchase credits, then retry.                                                                                        |
| `403`          | `account_suspended`          | Your account is suspended.                                                | Contact IPRoyal Support.                                                                                             |
| `403`          | `account_disabled`           | Your account is disabled.                                                 | Contact IPRoyal Support.                                                                                             |
| `404`          | `not_found`                  | No image was found at the URL, or the endpoint does not exist.            | Check the URL.                                                                                                       |
| `413`          | `payload_too_large`          | The request body is larger than 100 KB.                                   | Send only the documented fields.                                                                                     |
| `422`          | `blocked`                    | The target website's anti-bot protection blocked the request.             | Retry later or with another `geo_location`.                                                                          |
| `422`          | `no_data_extracted`          | `parse` was on, but the page had no structured data to extract.           | Retry without `parse` to get the HTML.                                                                               |
| `429`          | `concurrency_limit_exceeded` | Too many of your scrape requests are running at once.                     | Wait for a running request to finish. See [Limits](/scraping-tools/web-scraper-api-beta/making-a-request.md#limits). |
| `500` or `503` | `internal_error`             | A temporary problem on IPRoyal's side.                                    | Retry with backoff.                                                                                                  |
| `502`          | `upstream_unavailable`       | The scrape could not be completed, or usage data could not be read.       | Retry with backoff.                                                                                                  |
| `503`          | `capacity_exceeded`          | The service as a whole is at full capacity, regardless of your own limit. | Retry after a few seconds with backoff.                                                                              |

Requests that end in an error are not charged.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.iproyal.com/scraping-tools/web-scraper-api-beta/api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.