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

# Scraping API Overview

> 55 Tech Scraping API — route HTTP, browser, WebSocket, and AMQP requests through 80+ geo-distributed agents.

## What is the Scraping API?

The **Scraping API** by [55 Tech](https://55-tech.com/) lets you route HTTP, browser, WebSocket, and AMQP requests through a network of 80+ geo-distributed agents. Within seconds, the API automatically identifies the most reliable agents for each target — so your requests become instantly more successful without managing proxies yourself.

**What you can do:**

* **HTTP fetch** — GET/POST/PUT/PATCH/DELETE with full header, body, and cookie control
* **Browser fetch** — Full JavaScript rendering with cookies, screenshots, and custom JS evaluation
* **WebSocket relay** — Bidirectional frame relay (Socket.IO, SignalR, Centrifugo, GraphQL-WS, raw WebSocket)
* **AMQP consumer** — Stream RabbitMQ messages via Server-Sent Events (SSE)
* **Geo targeting** — Pin requests to specific countries or individual agents
* **Proxy chaining** — Route requests through your own proxy for additional IP flexibility
* **Response validation** — Verify expected content exists in rendered pages, auto-retry on different node if missing
* **Block detection** — Responses include a `meta.blocked` flag when access restrictions are detected

## Base URL

```
https://scraping-api.55-tech.com
```

## Authentication

Pass your API key via the `X-API-Key` header or (for WebSocket/AMQP) the `apiKey` body field. See [Authentication](/scraping-api/authentication) for details.

## Endpoints

| Endpoint                   | Method                        | Auth               | Description                                                        |
| -------------------------- | ----------------------------- | ------------------ | ------------------------------------------------------------------ |
| `/fetch`                   | GET, POST, PUT, PATCH, DELETE | Required           | Proxy HTTP requests through the agent network                      |
| `/browser`                 | GET                           | Header             | Fetch with JavaScript rendering (cookies, screenshots, JS eval)    |
| `/browser/stream`          | GET                           | Header             | Live browser session — stream network, WebSocket, DOM events (SSE) |
| `/ws`                      | WebSocket                     | In connect message | Bidirectional WebSocket relay                                      |
| `/amqp`                    | POST                          | In body or header  | AMQP/RabbitMQ consumer relay (SSE stream)                          |
| `/usage`                   | GET                           | Required           | Per-key usage metrics (requests, bytes, top domains)               |
| `/network/agents`          | GET                           | Required           | List all agents with slug, name, country                           |
| `/network/status`          | GET                           | Required           | Network summary (total nodes, nodes per country)                   |
| `/network/geo`             | GET                           | Required           | Agents grouped by country                                          |
| `/network/health/{domain}` | GET                           | Required           | Per-agent health state for a domain                                |
| `/debug/pick`              | GET                           | Required           | Preview which agent would be selected                              |
| `/healthz`                 | GET                           | No                 | Liveness probe                                                     |

## Control headers

These headers control routing and are stripped before forwarding to the target:

| Header          | Aliases                                         | Description                                                     | Example                        |
| --------------- | ----------------------------------------------- | --------------------------------------------------------------- | ------------------------------ |
| `X-Target-URL`  | —                                               | Target URL (no encoding needed, recommended)                    | `https://example.com/?foo=bar` |
| `X-Geo`         | `X-Geo-CC`, `X-Geo-Strict`, `X-CC`, `X-Country` | Restrict to specific countries (comma-separated ISO codes)      | `US,DE,AT`                     |
| `X-Expect-JSON` | —                                               | Hint that the target response is JSON                           | `1`                            |
| `X-Agent`       | —                                               | Route through specific agent(s) by slug or comma-separated list | `de1`, `de1,at5,us3`           |
| `X-Timeout`     | —                                               | Override request timeout in seconds                             | `60`                           |

## Rate limiting

Rate limits are **per API key**:

* Default: 10 requests/second
* WebSocket connections consume 1 token on connect (not per frame)

When rate limited, the API returns `429` with headers:

```
Retry-After: 1
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
```

Check your current usage with `GET /usage`.

## Fetch response format

All HTTP fetch responses follow this structure:

```json theme={null}
{
  "meta": {
    "status": 200,
    "final_url": "https://example.com/",
    "http_version": "HTTP/2",
    "elapsed_ms": 245,
    "blocked": false,
    "headers": { "content-type": "text/html" },
    "agent": { "id": "scraping-de1" },
    "bytes": 4521
  },
  "raw": "<!DOCTYPE html>...",
  "raw_json": null
}
```

| Field               | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `meta.status`       | HTTP status code from the target                                   |
| `meta.final_url`    | Final URL after redirects                                          |
| `meta.http_version` | HTTP version used (e.g. HTTP/2)                                    |
| `meta.elapsed_ms`   | Round-trip time in milliseconds                                    |
| `meta.blocked`      | `true` if access restrictions were detected in the response        |
| `meta.agent.id`     | Node that served the request (e.g. `scraping-de1`)                 |
| `meta.bytes`        | Response body size in bytes                                        |
| `raw`               | Response body as text (when not JSON)                              |
| `raw_json`          | Parsed JSON object (when response is valid JSON, otherwise `null`) |

## Next steps

<Columns cols={3}>
  <Card title="Authentication" icon="key" href="/scraping-api/authentication">
    Set up your API key.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/scraping-api/quickstart">
    Make your first proxied request.
  </Card>

  <Card title="Browser rendering" icon="window" href="/scraping-api/browser">
    Render JavaScript-heavy pages with a real browser.
  </Card>
</Columns>