# CrawlRelay API documentation

> CrawlRelay REST API at crawlrelay.com/api: API keys, errors, limits and endpoints for the balance, crypto top-ups, orders and proxies.

- URL: https://crawlrelay.com/docs/api/
- Last updated: 2026-10-14
- Publisher: CrawlRelay (https://crawlrelay.com)

Everything you do in your account can be scripted: check the balance, top up in crypto, buy a plan, create proxy credentials. JSON over HTTPS, one API key, examples in curl, Python and Node.js.

**Quick answer — How do I use the CrawlRelay API?**

Send HTTPS requests to `https://crawlrelay.com/api/v1` with your API key in the header `Authorization: Bearer API_KEY`. Create the key on the [developer page](https://crawlrelay.com/app/developer?lang=en) of your account (or with `POST /v1/api-keys`) and give it only the scopes it needs. Requests and responses are JSON; errors always come back as `{ "error": { "code", "message" } }`.

## At a glance

| Attribute | Value |
| --- | --- |
| Base URL | `https://crawlrelay.com/api/v1` |
| Format | JSON over HTTPS, UTF-8 |
| Authentication | API key: `Authorization: Bearer API_KEY` |
| API key scopes | `read`, `proxies`, `billing` |
| Money | USD as a string with 2 decimals (`"29.00"`) |
| Crypto amounts | Decimal strings, never floats (`"0.00045210"`) |
| Traffic | Bytes (1 GB = 1,000,000,000 bytes) |
| Dates | ISO 8601 in UTC (`2026-10-05T14:03:11Z`) |
| Version | `/v1` in every path |

## Authentication

Every request except the public catalogue carries an API key: `Authorization: Bearer API_KEY`. A key is shown in full **once**, when you create it: store it like a password. Revoke a key at any time; requests made with it then return `401 unauthorized`.

### Scopes

Give each key only what your script needs. A key without the required scope gets `403 forbidden`.

| Scope | What it allows |
| --- | --- |
| `read` | read everything (account, balance, services, usage). |
| `proxies` | change proxy settings and credentials (labels, auto-renew, new passwords), manage sub-users and manage the IP allowlist. |
| `billing` | create orders and top-ups, pay from the balance. |

*Check your balance*

```bash
curl -s "https://crawlrelay.com/api/v1/balance" \
  -H "Authorization: Bearer $API_KEY"
```

## Requests and responses

- **JSON in, JSON out**: send `Content-Type: application/json` with a body.
- **Lists** that can grow are paginated with `page` (from 1) and `perPage` (1–100, default 20) and return `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`. Short lists return `{ "data": [...] }`.
- **IDs** are opaque strings with a type prefix: `ord_` (order), `top_` (top-up), `txn_` (balance movement), `res_` (traffic subscription), `key_` (API key) and `ipw_` (IP allowlist entry).
- **Safe retries**: `POST /v1/orders` and `POST /v1/topups` accept an `Idempotency-Key` header (any unique string, kept 24 h). Replaying the same key returns the first response instead of buying or topping up twice.
- **Examples** show the shape of each answer: the IDs, IPs, amounts and dates in them are illustrative, the plan ids and prices are the real ones.

## Errors

Every error has the same body. `code` is stable and meant for your code; `message` is an English sentence that may change. Validation errors list each invalid field in `fields`. New codes may be added: handle unknown codes as a generic failure.

*422 validation_failed*

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": [
      {
        "field": "amountUsd",
        "code": "too_small",
        "message": "The minimum top-up is 25.00 USD."
      }
    ],
    "requestId": "req_2b7c0f"
  }
}
```

### Status codes

| Status | Meaning |
| --- | --- |
| `422` | `validation_failed`: one or more fields are invalid. |
| `401` | `unauthorized`: missing, invalid or expired token. |
| `402` | `insufficient_balance`: the balance does not cover the order. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: the API key lacks the required scope, or the account is suspended. |
| `404` | `not_found`: the resource does not exist or belongs to another account. |
| `409` | `conflict` (or a more specific code): the action is not possible in the current state. |
| `429` | `rate_limited`. |

## Rate limits

Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. Above the limit the API answers `429 rate_limited` with a `Retry-After` header (seconds): wait that long, then retry.

## API reference

- **[Account and balance](https://crawlrelay.com/docs/api/account/)** — Read your account settings, your prepaid USD balance and every movement of that balance (top-ups, purchases, refunds).
- **[Crypto top-ups](https://crawlrelay.com/docs/api/top-ups/)** — Top up the balance in crypto: get the deposit address and the exact amount, send exactly that amount, report the payment as sent (the transaction ID is optional), then follow the top-up until the balance is credited. The balance pays for any of our plans.
- **[Orders](https://crawlrelay.com/docs/api/orders/)** — List the plans and their prices, buy a plan from the balance (new service or more traffic) and read your past orders.
- **[Residential proxies and credentials](https://crawlrelay.com/docs/api/residential/)** — Manage traffic subscriptions (residential and rotating 4G/5G per GB): proxy credentials, sub-users with their own credentials and traffic cap, daily usage and the locations you can target in the proxy username.
- **[API keys and IP allowlist](https://crawlrelay.com/docs/api/api-keys/)** — Create and revoke API keys with limited scopes, and manage the IP allowlist: up to 10 source IPs allowed to use the proxies without a username and password.

> **Paying from a script** Plans are always paid from the prepaid USD balance. Top up in crypto (minimum 25.00 USD) with POST /v1/topups, then buy with POST /v1/orders. Both can go in one call: a top-up may carry the order in purchase, and the plan is bought as soon as the top-up is credited.

---

CrawlRelay: CrawlRelay is a developer-first rotating residential and 4G/5G mobile proxy service for scrapers and AI data pipelines: non-expiring pay-as-you-go traffic from $0.50/GB, paid in crypto, with no ID upload. No KYC — no ID, no selfie, no documents. Pay in crypto.