# HProxy Documentation
> The complete HProxy developer documentation as a single page. The authenticated REST API (base https://hproxy.com/api/v1): buy and manage proxies from a prepaid wallet, and run the Scraper API (116 endpoints across 23 platforms returning clean JSON, billed per successful call with exact fractional pricing). Plus two free no-key APIs: the live proxy list and the proxy checker. Source: https://hproxy.com/docs

---

# Overview

## HProxy Documentation

*Everything HProxy does, by REST: buy and manage proxies, run 116 scraper endpoints across 23 platforms, and three free no-key APIs. JSON in, JSON out.*

URL: https://hproxy.com/docs

Everything HProxy does, by REST. **Buy and manage proxies** from a prepaid wallet, run the **Scraper API** (116 endpoints across 23 platforms returning clean, structured JSON), or use the **free APIs**: a live proxy list and a proxy checker, no key required.

All authenticated endpoints are relative to the base URL `https://hproxy.com/api/v1` and return `application/json`. Money is always integer cents (`120` = $1.20), never floats.

**Your first call**

```bash
curl https://hproxy.com/api/v1/me -H "X-API-Key: hpx_your_key_here"
```

### Start here

- [Quickstart](https://hproxy.com/docs/quickstart): Key, first call, first result, in three steps.
- [Authentication](https://hproxy.com/docs/authentication): API keys, scopes and the spend cap.
- [Proxy API](https://hproxy.com/docs/proxy-api): Buy, deliver, renew: the whole loop from code.
- [Reselling guide](https://hproxy.com/docs/proxy-api/reselling): Run a proxy storefront on our API.
- [Scraper API](https://hproxy.com/docs/scrapers): Any supported page into structured JSON.
- [Scraper catalog](https://hproxy.com/docs/scrapers/catalog): All 116 endpoints, searchable.
- [Free proxy list API](https://hproxy.com/docs/free-proxy-list): The whole live pool in one call, no key.

## Quickstart

*Three steps to your first HProxy API call: create a key, verify it, then run a scraper or price a proxy plan.*

URL: https://hproxy.com/docs/quickstart

Three steps from zero to a working call.

1. **Create a key**: In your [dashboard](https://hproxy.com/dashboard) under **Settings → API keys**. The full key (prefixed `hpx_`) is shown once at creation, so store it somewhere safe.
2. **Verify it**: `GET /me` accepts any valid key and echoes the account it acts for, the fastest way to confirm everything is wired up.
3. **Make your first real call**: Run a scraper, or price a proxy product before buying it. Both examples below work as-is once you paste your key.

### Verify your key

**GET /me**

```bash
curl https://hproxy.com/api/v1/me -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "userId": "usr_1a2b3c",
  "email": "you@example.com",
  "scopes": ["buy", "scrape"],
  "dailySpendCapCents": null
}
```

### Your first real call

**Run a scraper**

```bash
curl "https://hproxy.com/api/v1/scrape/threads/search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Price a proxy plan**

```bash
curl "https://hproxy.com/api/v1/products/residential-lite/price?quantity=5" \
  -H "X-API-Key: hpx_your_key_here"
```

> [!NOTE] Scraper calls are billed **per successful call** at the exact listed price, every standard endpoint is $0.00149 per call ($1.49 per 1,000), with no per-call minimum. Errors, timeouts and rate limits are never charged; a lookup whose target does not exist counts as a call, because the platform was queried.

- [Authentication](https://hproxy.com/docs/authentication): How keys, scopes and the spend cap work.
- [Proxy API](https://hproxy.com/docs/proxy-api): Products, quotes, orders and plans.
- [Scraper API](https://hproxy.com/docs/scrapers): Endpoints, billing and the envelope.

## Authentication

*Create an API key in the dashboard and send it as X-API-Key or Authorization: Bearer. Keys carry buy and scrape scopes plus an optional daily spend cap.*

URL: https://hproxy.com/docs/authentication

Create an API key in your dashboard under **Settings → API keys**. The full key (prefixed `hpx_`) is shown once at creation, so store it somewhere safe. Send it on every request in the `X-API-Key` header, or as a `Bearer` token, both are accepted, same as Stripe or OpenAI.

**Both headers work**

```bash
curl https://hproxy.com/api/v1/wallet \
  -H "X-API-Key: hpx_your_key_here"

# Authorization: Bearer also works
curl https://hproxy.com/api/v1/wallet \
  -H "Authorization: Bearer hpx_your_key_here"
```

### Scopes

Each key carries **scopes** that gate what it can do. A key missing the required scope gets a `403` with code `missing_scope`.

| Field | Type | Description |
| --- | --- | --- |
| `buy` | `scope` | Create orders and deposits; read wallet, plans, orders and your proxies; generate lines; manage webhooks. |
| `scrape` | `scope` | Run the data scrapers. Independent of buy, so a scrape key can't place orders. |

### Daily spend cap

Each key can carry an optional **daily spend cap**. If a key's orders in the last 24h would exceed the cap, the next order is refused with `402` before any charge, so a leaked key can't drain your balance.

> [!WARNING] **Keep your keys secret**: Keep keys server-side. Never ship them in client code. Lost a key? Revoke it and create a new one in **Settings → API keys**.

## Rate limits & idempotency

*Per-key and per-IP rate limits with Retry-After, plus idempotent writes: Idempotency-Key for orders and deposits, X-Request-Id for scraper calls.*

URL: https://hproxy.com/docs/rate-limits

Requests are rate limited per key and per IP; exceed it and you get a `429` with a `Retry-After` header. Back off and retry. Scraper calls allow bursts of 100 with a sustained 20 requests per second per account.

### Idempotency

For any write (`POST /orders`, `POST /deposits`) send an `Idempotency-Key` header with any unique string you choose. A retry with the same key converges on the same order instead of creating a second one, so a dropped connection never double-charges.

**Idempotent order**

```bash
curl -X POST https://hproxy.com/api/v1/orders \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Idempotency-Key: your-unique-id-123" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"residential-lite","quantity":5}'
```

Scraper calls have the same protection under their own `X-Request-Id` header: a retry with the same value replays the original result and is never billed twice. See [Run a scraper](https://hproxy.com/docs/scrapers/run).

## Errors

*Errors return a non-2xx status and a JSON body with a human-readable error message plus a machine-readable code where useful.*

URL: https://hproxy.com/docs/errors

Errors return a non-2xx status and a JSON body with a human-readable `error` message, a machine-readable `code`, and the `requestId` of the call (the same value as the `X-Request-Id` response header). Scraper input errors add a `details` string naming the bad field. Branch on `code`, not on the message text: messages get reworded, codes do not. When you write to support about a failed call, include the `requestId` and we can find that exact request.

| Status | Meaning |
| --- | --- |
| `400` | Invalid product, quantity, targeting or scraper input, or a request body the endpoint does not understand (`unknown_field`, `invalid_body`). |
| `401` | Missing or invalid API key. |
| `402` | Wallet balance short, or per-key daily spend cap reached. |
| `403` | Key is missing the required scope, or the platform refused access to the target. |
| `404` | Unknown scraper, or the target does not exist (private, deleted, wrong handle). |
| `429` | Rate limited. Slow down and retry (Retry-After header). |
| `502` | Transient failure fetching from the platform. Retry shortly. Never billed. |
| `503` | The scraper is temporarily unavailable on our side. Retry shortly. Never billed. |

### Request body errors

Every write body is checked against its documented fields **before anything runs**. A field the endpoint does not know is refused, naming the field and the accepted set, so a typo or a guessed option can never be dropped in silence and charged for.

*code*

| Field | Type | Description |
| --- | --- | --- |
| `unknown_field` | `400` | The body carries a top-level field the endpoint does not read. The message names it and lists the accepted fields, e.g. `Unknown field 'separate_plan'. This endpoint accepts: product_id, quantity, fulfillment_meta, method, expected_amount_cents.` Nothing was charged. The most common case is `country` sent at the top level of `POST /orders`: a residential order carries no country at all (you choose it per line when you [generate lines](https://hproxy.com/docs/proxy-api/plans#generate)), and a dedicated-IP order puts it inside `fulfillment_meta`. See [Create an order](https://hproxy.com/docs/proxy-api/orders#orders-create). |
| `invalid_body` | `400` | The body is not valid JSON, or a field has the wrong type. The message includes the shape the endpoint expects. |

**Unknown field**

```json
{
  "error": "Unknown field 'separate_plan'. This endpoint accepts: product_id, quantity, fulfillment_meta, method, expected_amount_cents.",
  "code": "unknown_field",
  "requestId": "3f2b6d9c-7a1e-4c55-9d0e-2b8a5f6c1d47"
}
```

### Common codes

Every error on `/api/v1` carries a `code`. These are the ones a client is most likely to branch on; endpoint-specific codes (`insufficient_balance`, `already_applied`, `reseller_forbidden`) are documented on their endpoints.

*code*

| Field | Type | Description |
| --- | --- | --- |
| `unauthorized` | `401` | No key, an unknown key, or a revoked one. Send `X-API-Key: hpx_…`. |
| `account_blocked` | `403` | The acting account may not transact. Contact support. |
| `invalid_quantity` | `400` | `quantity` is missing, zero, negative or not a whole number. Quantities are whole GB or whole IPs; a fraction is refused rather than rounded. |
| `missing_product` | `400` | No `product_id` in the body. Ids come from `GET /products`. |
| `unsupported_method` | `400` | A payment `method` we do not offer. Orders take `wallet` or any rail; deposits take any rail: card, crypto, alipay, wechat, upi, momo, qris, pix, dana, fpx, oxxo, boleto, paymaya, grabpay_ph. The refusal names the full list. |
| `invalid_limit, invalid_offset` | `400` | A paging parameter that is not a usable number. A page size above the maximum is capped, not refused. |
| `invalid_count, invalid_sticky` | `400` | Line generation: `count` must be a whole number from 1 to 5000 and at most the plan's `generate.maxCount`, `stickyMinutes` a whole number of minutes, 0 or more. |
| `invalid_asn, invalid_os, invalid_strict, invalid_exclude, invalid_udp` | `400` | Line generation on Residential Premium: `asn` must be a whole AS number, `os` one of windows / android / ios / mac, `strict` and `udp` booleans, `excludeAsn` / `excludeCountries` / `excludeStates` / `excludeCities` lists of up to 20 entries. |
| `not_found` | `404` | The order, plan or webhook does not exist, or does not belong to the acting account. The two cases are deliberately indistinguishable. |
| `price_changed` | `409` | The order sent an `expected_amount_cents` that no longer matches the price. Nothing was charged; the body carries the current `amountCents`, `unitPriceCents` and `quantity`, so you can show the new total and ask your buyer again. |

### Gateway status codes

A generated **Residential Premium** line answers with its own status codes when a request cannot be served. They come from the proxy gateway, not from `/api/v1`, so they carry no `code` field; this is what each one means and what to do.

*Status*

| Field | Type | Description |
| --- | --- | --- |
| `407` | `Proxy auth` | The username or password on the line is wrong, or the line was generated for another plan. Regenerate the line; a whitelisted IP connects without credentials. |
| `403` | `Bad targeting` | A targeting token the gateway does not accept: a state and a city together, an ISP without a country, a misspelt place. Pick places and networks from the `/geo/*` lists. |
| `464` | `Destination refused` | The target host, port or protocol is blocked by the network's usage policy. |
| `465` | `No IP for the target` | Nothing free matches the targeting right now. Widen it (drop the city or ISP), or generate with `strict: false` to fall back within the country. |
| `466` | `Plan traffic used up` | The plan's GB are spent. Top up the plan; lines keep working as soon as the balance lands. |
| `467` | `Session traffic cap` | The session used up a traffic cap set for that one session. Lines generated here never set one; a username edited by hand with a `-limit-` token gets this once that cap is spent. Use a new session id. |
| `568` | `Session error` | The network's own error on one sticky session. A session can keep answering 568 after it was released, so retrying the same line does not clear it. Change the session id in the username (or generate the line again) and the next request binds a fresh IP; releasing that session once more also clears it. |
| `5xx` | `Gateway error` | Retry with backoff. Persisting errors are ours to chase: tell support the time and the line's port. |

### Scraper error codes

A failed scrape names its cause in `code` so you can handle each one differently instead of retrying everything. **Nothing that fails on our side is billed** — errors, timeouts and rate limits all cost nothing. The one exception is a target that does not exist: the platform was queried and answered, so that call is billed like any other, and each code below says which it is.

*code*

| Field | Type | Description |
| --- | --- | --- |
| `target_not_found` | `404` | The profile, post or ID is not there. Private, deleted, or the handle is wrong. Retrying will not help; fix the input. **Billed**, because the platform was queried and gave us its answer. |
| `target_restricted` | `403` | The platform refused it: age-gated, region-locked or login-only content. Retrying will not help. Not billed. |
| `bad_input` | `400` | The endpoint rejected these parameters. Check the required parameters for that endpoint. Several accept **one of** a pair (a handle *or* a user id) and reject a call carrying neither. Not billed. |
| `provider_failed` | `502` | A transient fetch failure. Safe and sensible to retry, ideally with a short backoff. Not billed. |
| `upstream_credits_exhausted` | `503` | A capacity problem on our side, not a problem with your request. Retry shortly; if it persists, contact us. Not billed. |
| `upstream_auth_rejected` | `503` | As above: ours to fix, not yours. Retry shortly and tell us if it continues. Not billed. |

**Error response**

```json
{
  "error": "No data found for this target. It may be private, deleted, or the handle/URL may be wrong.",
  "code": "target_not_found"
}
```

> [!NOTE] **Changed recently**: Before 2026-07-30 every failed scrape answered `502` with the same generic message, so a mistyped handle looked identical to an outage. The statuses and codes above are what the API returns now.

## Account & wallet

*GET /me verifies a key, GET /wallet reads your balance in integer cents, POST /deposits tops it up by card or crypto.*

URL: https://hproxy.com/docs/account

The shared plumbing every integration uses: verify a key, read the wallet that pays for both proxy orders and scraper calls, and top it up. Money is always integer cents.

#### GET /api/v1/me

**Who am I.** The fastest check that a key works. Accepts **any** valid key (no scope needed) and echoes the account it acts for plus the scopes the key carries.

**cURL**

```bash
curl https://hproxy.com/api/v1/me -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "userId": "usr_1a2b3c",
  "email": "you@example.com",
  "scopes": ["buy", "scrape"],
  "dailySpendCapCents": null
}
```

#### GET /api/v1/wallet

**Get wallet.** Your current wallet balance, in integer cents.

**Request**

```bash
curl https://hproxy.com/api/v1/wallet -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{ "balanceCents": 25765, "currency": "USD" }
```

#### POST /api/v1/deposits

**Top up wallet.** Add funds to your wallet. Returns a hosted `payUrl` to complete the payment by card or crypto. Amount is in cents.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_cents` | `integer` | required | Amount to add, in cents. Sub-minimum top-ups are bumped to the method floor. |
| `method` | `string` | optional | "card" (default) or "crypto". |

**Request**

```bash
curl -X POST https://hproxy.com/api/v1/deposits \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Idempotency-Key: deposit-2026-07-11-001" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":5000,"method":"crypto"}'
```

**Response**

```json
{
  "depositId": "ord_...",
  "payUrl": "https://pay.example.com/checkout/...",
  "amountCents": 5000,
  "currency": "USD"
}
```

## Announcements and service notices

*GET /announcements is the house feed for software: maintenance windows, incidents, pricing changes and action-required notices about the API. The same publish is pushed as a webhook and, when action is needed, emailed.*

URL: https://hproxy.com/docs/announcements

When something changes on our side, one record is written and every channel reads it: the bell in your dashboard, this endpoint, the `announcement.published` [webhook](https://hproxy.com/docs/proxy-api/webhooks), and for notices that need action, an email to every account holding an API key. You never have to watch a status page to learn that a field was renamed or a behavior corrected.

#### GET /api/v1/announcements

**List live notices.** Every published notice addressed to an audience your account belongs to, newest first, at most 50. Accepts **any** valid key (no scope needed). Poll it once an hour at most: it is not a queue, and nothing is lost by polling less. Branch on `kind`.

| Field | Type | Description |
| --- | --- | --- |
| `kind` | `string` | `INFO`, `MAINTENANCE`, `INCIDENT`, `RELEASE`, `PRICING` or `ACTION_REQUIRED`. Treat `ACTION_REQUIRED` as a ticket: an integration has something to change, usually with a date in the body. |
| `audience` | `string` | `ALL`, `CUSTOMERS`, `PARTNERS` or `DEVELOPERS`. Every account holding an API key is in `DEVELOPERS`, so notices about the API always reach you here. |
| `publishedAt, expiresAt` | `RFC 3339` | The feed is ordered by `publishedAt`. An expired notice (a maintenance window that has passed) drops out on its own; `expiresAt` is `null` while a notice stands. |
| `linkHref, linkLabel` | `string` | An optional deep link, relative to hproxy.com or absolute. `null` when there is nothing more to read. |
| `unread` | `boolean` | Read state belongs to the account and is set from the dashboard, not from this endpoint. A key-only integration sees `true` until someone opens the notice there. |

**Request**

```bash
curl https://hproxy.com/api/v1/announcements -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "announcements": [
    {
      "id": "1f3c9a7e-…",
      "title": "Order bodies are now strict: unknown fields return 400",
      "body": "From 2026-09-03, POST /orders and every other write endpoint refuse a top-level field they do not read with 400 unknown_field. Check your client for fields outside the documented set.",
      "kind": "ACTION_REQUIRED",
      "audience": "DEVELOPERS",
      "publishedAt": "2026-09-03T18:40:12+00:00",
      "expiresAt": null,
      "linkHref": "/docs/errors",
      "linkLabel": "Errors",
      "unread": true
    }
  ]
}
```

### Get pushed instead

Subscribe a [webhook](https://hproxy.com/docs/proxy-api/webhooks) to `announcement.published` and the same publish reaches your endpoint, signed like every other event. The payload carries the id, title, kind and audience; fetch the body from this endpoint if you need it.

### Email, for what cannot wait

Notices that need action from you are also emailed to the address on every account that holds an API key, from the same sender as your order confirmations. That is the one channel a quiet integration still receives, so keep the account email one that a person reads.

> [!NOTE] **What it is not**: This is a feed of changes we make on purpose. Live product availability is the `available` flag on [GET /products](https://hproxy.com/docs/proxy-api/products), and order outcomes live on the order itself and its webhooks.

## OpenAPI spec

*GET /api/v1/openapi.json returns the full machine-readable OpenAPI 3.1 document for codegen, Postman or Insomnia.*

URL: https://hproxy.com/docs/openapi

The full machine-readable OpenAPI 3.1 document. Feed it to your codegen or a client like Postman or Insomnia to generate a typed SDK.

**GET /openapi.json**

```bash
curl https://hproxy.com/api/v1/openapi.json
```

Two more machine-readable surfaces: the complete scraper catalog as JSON at `GET /api/v1/scrapers` (no key required, see the [catalog](https://hproxy.com/docs/scrapers/catalog)), and this entire documentation as one markdown page at [/llms-full.txt](https://hproxy.com/llms-full.txt) for AI assistants.

---

# Proxy API

## Proxy API

*Buy and deliver residential, ISP, datacenter and mobile proxies programmatically: quotes, wallet orders, line generation, proxy delivery, webhooks and renewals.*

URL: https://hproxy.com/docs/proxy-api

A small, predictable REST API for running a proxy business from your own code. You prepay from your wallet balance, every order is idempotent so a retry never double-charges, and by default nothing ever silently falls back to charging a card you didn't pick. The whole loop is programmatic: buy, **deliver** (generated residential lines or dedicated IPs with credentials), get **pushed** on fulfillment, renew.

1. **List products**: `GET /products`, the buyable catalog with pricing model, quantity bounds and each product's targeting contract.
2. **Get a quote**: `GET /products/{id}/price?quantity=N`, the exact amount the order will charge. Add `country` and `period_days` for dedicated IPs.
3. **Place the order**: `POST /orders`, debits your wallet (or returns a hosted payUrl for card/crypto).
4. **Deliver**: A gateway product (`delivery` is `lines`: every product priced per GB): `POST /plans/{id}/generate` for targeted `host:port:user:pass` lines. Dedicated addresses (`delivery` is `addresses`): `GET /proxies?order_id=…` for the IPs with credentials.
5. **Get pushed**: Register a [webhook](https://hproxy.com/docs/proxy-api/webhooks) and receive `order.fulfilled` instead of polling.

- [Products & pricing](https://hproxy.com/docs/proxy-api/products): The catalog and server-side quotes.
- [Orders](https://hproxy.com/docs/proxy-api/orders): Create, list, poll, and renew.
- [Plans & generation](https://hproxy.com/docs/proxy-api/plans): What you own, and generating lines.
- [Your proxies](https://hproxy.com/docs/proxy-api/proxies): Dedicated IPs with credentials, by order.
- [Webhooks](https://hproxy.com/docs/proxy-api/webhooks): Signed pushes on fulfillment.
- [Reselling guide](https://hproxy.com/docs/proxy-api/reselling): The end-to-end storefront loop.
- [Reseller API](https://hproxy.com/docs/proxy-api/reseller): Act as each of your customers, at your rates.

## Products & pricing

*GET /products lists the buyable proxy catalog. GET /products/{id}/price returns the exact server-authoritative amount an order will charge.*

URL: https://hproxy.com/docs/proxy-api/products

#### GET /api/v1/products

**List products.** The buyable catalog: for each product its family, its shape (what buying and delivery look like), its unit, description and features, its lifecycle, its published price, its quantity bounds and a how-to with the exact calls for that shape.

**Request**

```bash
curl https://hproxy.com/api/v1/products -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "products": [
    {
      "id": "residential-lite",
      "name": "Residential Lite",
      "family": "residential",
      "shape": "gateway_gb",
      "unit": "GB",
      "delivery": "lines",
      "renewal": "topup",
      "state": "active",
      "description": "Budget-friendly rotating residential proxies at the lowest price per GB",
      "features": ["country-targeting", "sticky-sessions", "rotation-control"],
      "available": true,
      "billing": { "payg": true, "subscription": true, "intervals": ["month","year"] },
      "minQuantity": 1,
      "maxQuantity": 10000,
      "price": { "kind": "ladder", "unit": "GB", "unitCents": 50, "rungs": [ … ], "quote": "/api/v1/products/residential-lite/price?quantity=N" },
      "howTo": { "summary": "Buy gigabytes, then generate as many proxy lines as you like against the plan.", "steps": [ … ] }
    }
  ]
}
```

#### GET /api/v1/products/{id}

**Read one product.** One product by its id, or by any id it used to carry, with its lifecycle. A retired product answers `200` with `state: "retired"` and `successorId`, never a `404`, so a menu built from an old catalog can tell its customer what to buy now. `state` is `active`, `parked` (listed, orders answer `409 product_unavailable` until it is back) or `retired`. `family` names the umbrella (`residential`, `isp`, `mobile`, `ipv4`, `ipv6`) so a storefront groups products without guessing from the name. `shape` says what buying and delivery look like, and it is what to key an integration on, never a list of ids: `gateway_gb` and `gateway_time` are a plan you generate lines from (`delivery` is `lines`), `addresses` and `addresses_mobile` are dedicated IPs that land in [proxies](https://hproxy.com/docs/proxy-api/proxies) (`delivery` is `addresses`). `renewal` is `topup` (order again, the units land on the plan you hold), `repurchase` (a fresh plan for a fresh period) or `extend` (an extension naming the addresses to keep). `howTo` spells the exact calls for that shape, from the price to the first use, with the targeting fields its network takes. A product we add on a known shape works in your code the day it lands.

**Request**

```bash
curl https://hproxy.com/api/v1/products/residential-lite -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "id": "residential-lite",
  "name": "Residential Lite",
  "family": "residential",
  "state": "active",
  "successorId": null,
  "available": true,
  "shape": "gateway_gb",
  "unit": "GB",
  "delivery": "lines",
  "renewal": "topup",
  "minQuantity": 1,
  "maxQuantity": 10000,
  "billing": { "payg": true, "subscription": true, "intervals": ["month","year"] }
}
```

#### GET /api/v1/products/{id}/price

**Price a product.** A server-authoritative quote: the exact amount `POST /orders` will charge for the same inputs. Pass the quantity as a query parameter. For dedicated per-IP products, add `country` and `period_days` to quote the exact targeting you'll order. Omitted, they default to `USA` / 30 days.

**On a reseller key** the answer also says what the order costs **you**: `yourCostCents` is what we debit from your balance when one of your customers places it, `amountCents` is what that customer pays (your retail or markup, else our price), `marginCents` is the difference, `listCents` is our own price, and `note` spells out which is which. To see every period of a country at once, use the [price list](#price-list).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `quantity` | `integer (query)` | required | GB for residential, or number of IPs for dedicated products. |
| `country` | `string (query)` | optional | Per-IP products: target country, alpha-3 (e.g. USA, DEU). Default USA. |
| `period_days` | `integer (query)` | optional | Per-IP products: rental period in days (e.g. 30, 90). Default 30. |

**Request**

```bash
curl "https://hproxy.com/api/v1/products/residential-lite/price?quantity=5" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "productId": "residential-lite",
  "quantity": 5,
  "unitPriceCents": 100,
  "amountCents": 500,
  "currency": "USD",
  "billingType": "PAYG"
}
```

#### GET /api/v1/products/{id}/price-list

**Price list for a country.** For **dedicated per-IP products** (ISP, IPv4, IPv6 and mobile IPs): every rental period of one country priced in one call, so you can print a price table without one quote per period. Each line carries `listCents`, our price for the order, and `available` (false when that period is sold out right now). Mobile answers one line per carrier, service and rotation mode for one period instead (pick it with `period_days`; the carrier ids go straight into `fulfillment_meta`), from the day's price refresh, so quote one mobile order with [price](#price) for the exact figure.

**On a reseller key every line also says what it costs you**: `yourCostCents` is what we debit from your balance when one of your customers orders that line, `customerCents` what that customer pays (our price times your markup), and `marginCents` what you keep; `partner` states your discount, your markup and whether the product is on your catalog. The same table is under Pricing in your business dashboard. Products sold per GB or per speed tier answer `400 no_price_list`: they have one price per unit, which [price](#price) quotes.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | `string (query)` | required | Alpha-3 from [options](#options), e.g. USA. |
| `quantity` | `integer (query)` | optional | How many IPs every line prices. Default: the product's smallest order (1, or 10 for IPv6). A bigger order can cost less per IP. |
| `period_days` | `integer (query)` | optional | Mobile only: the period every carrier is priced for. Default 30. |

**Request**

```bash
curl "https://hproxy.com/api/v1/products/isp/price-list?country=USA" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response (reseller key)**

```json
{
  "productId": "isp",
  "unit": "IP",
  "country": "USA",
  "quantity": 1,
  "currency": "USD",
  "countries": [{ "alpha3": "USA", "name": "United States" }, { "alpha3": "TUR", "name": "Turkey" }],
  "partner": { "discountPct": 20, "markup": 1.3, "sellable": true },
  "lines": [
    { "days": 7, "period": "1 week", "available": true, "listCents": 250, "yourCostCents": 200, "customerCents": 325, "marginCents": 125 },
    { "days": 30, "period": "1 month", "available": true, "listCents": 270, "yourCostCents": 216, "customerCents": 351, "marginCents": 135 }
  ],
  "note": "listCents is our own price for this order. yourCostCents is what we debit from your balance when one of your customers orders it …"
}
```

#### GET /api/v1/products/{id}/options

**Available countries & periods.** For **dedicated per-IP products** (IPv4, IPv6, ISP), the live list of countries you can order and the rental periods available, so you can build a picker without hardcoding anything. Countries come back as `{ name, alpha3 }` and are **kept current for you**: the list is refreshed from stock and a country that has run out is removed automatically, so what this returns is always orderable. Feed an `alpha3` straight into the `country` of [price](#price) and [orders](https://hproxy.com/docs/proxy-api/orders), and a `days` into `period_days`. Gateway products (`delivery` is `lines`: residential, mobile, ISP rotating, IPv4 and IPv6 per GB) have no per-country configurator and return `400 no_options`: they target by country at generation time instead (see [generate](https://hproxy.com/docs/proxy-api/plans#generate)).

**Request**

```bash
curl https://hproxy.com/api/v1/products/ipv4/options \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "productId": "ipv4",
  "unit": "IP",
  "minQuantity": 1,
  "maxQuantity": 1000,
  "countries": [
    { "name": "United States", "alpha3": "USA" },
    { "name": "Germany", "alpha3": "DEU" },
    { "name": "United Kingdom", "alpha3": "GBR" }
  ],
  "periods": [
    { "days": 30, "label": "30 days" },
    { "days": 90, "label": "90 days" }
  ]
}
```

## Orders

*POST /orders buys a product from your wallet (or returns a hosted payUrl for card and crypto). GET /orders lists history, GET /orders/{id} polls one.*

URL: https://hproxy.com/docs/proxy-api/orders

#### POST /api/v1/orders

**Create an order.** Buy a product. By default this is a wallet prepay: it debits your balance and returns immediately, or fails with `402` if the balance is short (it never silently charges a card you didn't pick). Set `method` to `"card"` or `"crypto"` to get a hosted `payUrl` back instead. Always send an `Idempotency-Key` so a retry never double-charges; on a reseller key an order without one is refused.

The body takes **only the five fields below**. Anything else, including a top-level `country`, is refused with `400 unknown_field` before anything is charged. What goes in it depends on the product's `delivery` on [GET /products](https://hproxy.com/docs/proxy-api/products).

**Residential and other gateway products** (`delivery` is `lines`): send `product_id` and `quantity`, nothing else. There is no country in the order. You choose the country for each line when you [generate lines](https://hproxy.com/docs/proxy-api/plans#generate) from the plan, so one plan serves every country. A package size is the `quantity` (1 GB is `1`, 10 GB is `10`), never a separate product id, and it is a whole number from the product's `minQuantity`.

**Dedicated IPs** (`delivery` is `addresses`: IPv4, IPv6, ISP and mobile IPs): `quantity` counts IPs, and the targeting goes inside `fulfillment_meta`, for example `{"country": "DEU", "period_days": 30}`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `product_id` | `string` | required | A product id from GET /products, e.g. "residential-lite". |
| `quantity` | `integer` | required | A whole number; a fraction is refused. GB for residential and other per-GB products, or number of IPs for dedicated products, between the product's `minQuantity` and `maxQuantity`. For renewals: the number of ids. |
| `method` | `string` | optional | "wallet" (default), "card" or "crypto". card/crypto return a payUrl. |
| `fulfillment_meta` | `object` | optional | Dedicated IPs: country (alpha-3, e.g. "DEU"), period_days, and operator_id on mobile. For a RENEWAL of dedicated proxies: {"kind": "extension", "ids": ["…"], "period_days": 30} (ids from GET /proxies, ownership-checked server-side). Leave it out for residential and other per-GB products: you choose their country per line at POST /plans/{id}/generate. |
| `expected_amount_cents` | `integer` | optional | The total you showed the buyer (the `amountCents` of your quote). If the price moved in between, the order is refused with `409 price_changed` carrying the new `amountCents`, and nothing is charged. Omit it to be charged the price at the moment of the order. |

**Request (residential)**

```bash
# Residential: product_id + quantity (GB). No country here:
# the country is chosen per line at POST /plans/{id}/generate.
curl -X POST https://hproxy.com/api/v1/orders \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Idempotency-Key: order-2026-07-11-001" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"residential-lite","quantity":1}'
```

**Request (dedicated IPs)**

```bash
# Dedicated IPs: the country (alpha-3) and the period go in fulfillment_meta
curl -X POST https://hproxy.com/api/v1/orders \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Idempotency-Key: order-2026-07-11-002" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"ipv4","quantity":5,"fulfillment_meta":{"country":"DEU","period_days":30}}'
```

**201 Created**

```json
{
  "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821",
  "amountCents": 120,
  "currency": "USD",
  "status": "processing"
}
```

#### GET /api/v1/orders

**List orders.** Your order history, newest first, one page at a time. Without parameters you get the 15 most recent.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer (query)` | optional | Page size, 1 to 200. Default 15. A larger value is capped at 200. |
| `offset` | `integer (query)` | optional | Rows to skip, newest first. Default 0. Page 3 of 50 is `limit=50&offset=100`. |

**Request**

```bash
curl "https://hproxy.com/api/v1/orders?limit=50&offset=0" -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "orders": [
    {
      "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821",
      "productId": "residential-lite",
      "type": "PURCHASE",
      "status": "PAYMENT_RECEIVED",
      "quantityGb": 1.0,
      "amountCents": 120,
      "currency": "USD",
      "createdAt": "2026-07-11T09:46:05.191+00:00"
    }
  ]
}
```

#### GET /api/v1/orders/{id}

**Get an order.** Fetch a single order by its id to poll fulfillment status. Once it reads `completed`, a dedicated-IP order's proxies are ready at [GET /proxies?order_id=…](https://hproxy.com/docs/proxy-api/proxies).

**Request**

```bash
curl https://hproxy.com/api/v1/orders/ord_8f49...8821 \
  -H "X-API-Key: hpx_your_key_here"
```

> [!TIP] Skip the polling loop entirely: register a [webhook](https://hproxy.com/docs/proxy-api/webhooks) and get pushed `order.fulfilled` / `order.failed` / `order.refunded` the moment they happen.

## Plans & line generation

*GET /plans lists the plans a key owns, each with its status. POST /plans/{id}/generate returns host:port:user:pass lines with country, city, ISP and sticky-session targeting.*

URL: https://hproxy.com/docs/proxy-api/plans

#### GET /api/v1/plans

**List plans.** Your plans: residential GB balances and dedicated allocations. By default the list holds the plans that can be used now; add `?status=all` to include the ones that ran out or were switched off. A plan is never deleted. Every plan carries `status`: `active`, `used_up` (its traffic ran out, so it was switched off at 0 GB) or `inactive` (switched off with GB still on it: refunded, moved or turned off by hand). Only an `active` plan generates lines. An order for a customer whose plan is `used_up` refills that same plan: it turns `active` again with the same login, so nothing changes on your customer's side. The `id` is what you pass to the endpoints below; `label` is your own tag (see PATCH), `null` until you set it. `productId` is the catalog id you ordered (`residential-lite`, `residential-premium`, …) and the field to branch on; `product` is our internal family name, kept for compatibility, and it can change when we move a product to a new pool. `dataGbTotal` and `dataGbRemaining` here are the usage sync's reading, taken about every 30 minutes (a plan bought moments ago shows its full balance until the next pass); `GET /plans/{id}` refreshes them from the network on the call and carries `usageAsOf`. The network enforces every plan's cap itself, in real time.

**Request**

```bash
curl "https://hproxy.com/api/v1/plans?status=all" -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "plans": [
    {
      "id": "cmjfmhhpd004c4i4hqsk3mzrr",
      "product": "residential-premium",
      "productId": "residential-premium",
      "status": "active",
      "dataGbTotal": 1.0,
      "dataGbRemaining": 1.0,
      "expiresAt": null,
      "createdAt": "2025-12-21T11:07:14.785Z",
      "label": "customer-1042"
    },
    {
      "id": "cmk2b7xq9001s8f3lw4tn6v0e",
      "product": "residential-lite",
      "productId": "residential-lite",
      "status": "used_up",
      "dataGbTotal": 5.0,
      "dataGbRemaining": 0.0,
      "expiresAt": null,
      "createdAt": "2026-03-02T09:14:22.104Z",
      "label": "customer-2077"
    }
  ]
}
```

#### GET /api/v1/plans/{id}

**Get one plan.** A single plan you own, whatever its `status`: the per-customer read for a reseller dashboard. A plan whose traffic ran out answers `200` with `"status": "used_up"` and `dataGbRemaining` 0, so you can tell your customer their GB is spent; only an id that is not yours is a `404`. `dataGbRemaining` is refreshed from the network's own meter on this call (one network read per plan per minute; between reads you get the last reading), and `usageAsOf` says when that reading was taken. The list endpoint carries the usage sync's reading instead, taken about every 30 minutes, so poll this door when you show a customer what is left. The network enforces the plan's cap itself, in real time: a customer cannot use more than the plan holds, whatever the figure here shows between readings.

**Request**

```bash
curl https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "id": "cmjfmhhpd004c4i4hqsk3mzrr",
  "product": "residential-premium",
  "productId": "residential-premium",
  "status": "active",
  "dataGbTotal": 10.0,
  "dataGbRemaining": 3.2,
  "expiresAt": null,
  "createdAt": "2026-07-23T01:07:14.785Z",
  "label": "customer-1042"
}
```

#### PATCH /api/v1/plans/{id}

**Label a plan.** `PATCH` a plan with your own reference, e.g. which of YOUR customers it belongs to. Pure metadata: it changes nothing about pricing, traffic or generation, and it comes back in `GET /plans`, `GET /plans/{id}` and in [webhook](https://hproxy.com/docs/proxy-api/webhooks) payloads, so every signal is already attributed to your customer. `null` (or an empty body) clears it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string | null` | optional | 1 to 64 characters, no control characters. null/omitted clears. |

**Request**

```bash
curl -X PATCH https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"label": "customer-1042"}'
```

**Response**

```json
{
  "id": "cmjfmhhpd004c4i4hqsk3mzrr",
  "product": "residential-premium",
  "productId": "residential-premium",
  "dataGbTotal": 10.0,
  "dataGbRemaining": 10.0,
  "expiresAt": null,
  "createdAt": "2026-07-23T01:07:14.785Z",
  "label": "customer-1042"
}
```

#### GET /api/v1/plans/{id}/stats

**Traffic statistics.** How a **Residential Premium** plan was used, bucket by bucket: bytes, requests and success rate straight from the network's own metering of that plan. Add `/targets` to the path (`GET /plans/{id}/stats/targets`) for the breakdown by target host and country, heaviest first (`rows[]` with `host`, `country`, `bandwidthBytes`, `requests`, `successRate`, `avgLatencyMs`; `limit` 1 to 500). Plans on other products answer 400.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `days` | `integer` | optional | Window ending now, 1 to 30. Default 7. |
| `granularity` | `string` | optional | "hour" (windows up to 29 days) or "day". Default: hour up to 2 days, else day. |

**Request**

```bash
curl "https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/stats?days=7" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "planId": "cmjfmhhpd004c4i4hqsk3mzrr",
  "days": 7,
  "granularity": "day",
  "from": "2026-08-28T00:00:00.000Z",
  "to": "2026-09-04T00:00:00.000Z",
  "points": [
    { "at": "2026-09-04T00:00:00.000Z", "bandwidthBytes": 7497, "requests": 15, "successfulRequests": 15, "failedRequests": 0, "successRate": 100 }
  ],
  "totals": { "bandwidthBytes": 7497, "bandwidthGb": 0.0, "requests": 15, "successfulRequests": 15, "successRate": 100 }
}
```

#### GET /api/v1/plans/{id}/whitelist

**IP whitelist.** The IP addresses that may use a **Residential Premium** plan WITHOUT the password (IP authentication), up to 150 per plan. `GET` lists them, `POST` adds (`{"ips": ["203.0.113.9", {"ip": "2001:db8::1", "description": "office"}]}`), `DELETE` removes (`{"ips": ["203.0.113.9"]}`); each answers the resulting list. Every entry must be a valid IPv4 or IPv6 address. A whitelisted connection carries no username, so it takes no targeting: it rotates through any country on the rotating ports and holds one IP per sticky port. Use the generated lines (password included) whenever you need a country, state, city or ISP. Whitelist only addresses you alone control: everything that connects from a whitelisted IP spends this plan's traffic, and a shared office, VPN or cloud egress address is shared with everyone behind it. Plans on other products answer 400.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ips` | `array` | required | POST / DELETE body: IP strings, or `{ip, description}` objects (description up to 80 characters). |

**Request**

```bash
curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/whitelist \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ips": [{"ip": "203.0.113.9", "description": "office"}]}'
```

**Response**

```json
{
  "planId": "cmjfmhhpd004c4i4hqsk3mzrr",
  "max": 150,
  "ips": [ { "ip": "203.0.113.9", "description": "office" } ]
}
```

#### GET /api/v1/plans/{id}/sessions

**Sticky sessions.** The sticky sessions a **Residential Premium** plan holds right now, up to 250 per page: the port and its protocol, the session label the line carried, the exit country, the session's full length, the seconds it has run and the seconds it has left. A session whose line was generated here also carries `targeting` (what the line aimed at: country, state or city, `asn`, `os`, exclusions, `strict`, `udp`), `line` (the exact line, with the plan's password) and `generatedAt`; a session opened with a session id of your own carries null in all three. A port holds any number of sessions, one per session id, so `total` can be far larger than the number of ports; read further pages with `page`. A sticky line opens its session on the first request. `POST /plans/{id}/release-sessions` ends sessions and takes exactly one of three bodies: `{"sessions": [{"port": 10000, "sessionId": "a41f9c02"}]}` ends exactly those (up to 1,000 per call), `{"ports": [10000]}` ends every session on those ports (up to 200 ports), `{"all": true}` ends every open session. The next request on a released line draws a fresh IP. The answer carries `releasedSessions` (how many ended), `released` (their ports), `notOpen` (named ports that held none) and `remaining`: a `ports` or `all` release ends at most 5,000 sessions per call, so call again until `remaining` is 0. Plans on other products answer 400.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `page` | `integer` | optional | List only: the page to read, from 1. Default 1. |
| `pageSize` | `integer` | optional | List only: sessions per page, 1 to 250. Default 250. |
| `sessions` | `object[]` | optional | Release only: 1 to 1,000 `{port, sessionId}` pairs, as the list shows them. Exactly those sessions end. |
| `ports` | `integer[]` | optional | Release only: 1 to 200 sticky ports. Every open session on them ends. |
| `all` | `boolean` | optional | Release only: `true` ends every open session on the plan. |

**Request**

```bash
curl "https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/sessions" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "planId": "cmjfmhhpd004c4i4hqsk3mzrr",
  "total": 3,
  "page": 1,
  "pageSize": 250,
  "sessions": [
    { "port": 10000, "protocol": "http", "sessionId": "k3m9x20000", "country": "DE", "lifetimeSeconds": 1800, "elapsedSeconds": 587, "remainingSeconds": 1213,
      "targeting": { "country": "de", "city": "berlin", "os": "windows" },
      "line": "premium.hproxy.com:10000:USERNAME-type-residential-country-de-city-berlin-os-windows-session-k3m9x20000-lifetime-30:PASSWORD",
      "generatedAt": "2026-09-15T14:02:11Z" },
    { "port": 10000, "protocol": "http", "sessionId": "c7d1e8b3", "country": "US", "lifetimeSeconds": 3600, "elapsedSeconds": 120, "remainingSeconds": 3480,
      "targeting": null, "line": null, "generatedAt": null },
    { "port": 12000, "protocol": "socks5", "sessionId": "p7q2d80000", "country": "US", "lifetimeSeconds": 86400, "elapsedSeconds": 489, "remainingSeconds": 85911,
      "targeting": { "country": "us", "asn": 7922, "udp": true },
      "line": "premium.hproxy.com:12000:USERNAME-type-residential-country-us-asn-7922-requireUdp-true-session-p7q2d80000-lifetime-1440:PASSWORD",
      "generatedAt": "2026-09-15T13:40:57Z" }
  ]
}
```

**Release one session**

```bash
curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/release-sessions \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"sessions": [{"port": 10000, "sessionId": "a41f9c02"}]}'
```

**Release every session**

```bash
curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/release-sessions \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"all": true}'
# {"ok": true, "released": [10000, 12000], "releasedSessions": 3, "notOpen": [], "remaining": 0}
```

#### POST /api/v1/plans/{id}/password

**Rotate the proxy password.** Replace the password behind a **residential** plan's lines with a fresh one, confirmed by the network before it is stored, and answer the new `username` and `password` once. Every line generated before the call stops working within seconds; generate again afterwards. Use it when a line has leaked. Throttled to three rotations per account every ten minutes, because each call cuts every line that account is running. No body. Residential Plus plans answer 400.

**Request**

```bash
curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/password \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "ok": true,
  "username": "hproxy_k2m9x4qp7wz1",
  "password": "3f1c2a9e-8b7d-4e6f-a1b2-c3d4e5f60718"
}
```

#### POST /api/v1/plans/{id}/generate

**Generate proxy lines.** Turn a **gateway** plan you own into ready-to-use proxy lines, fully programmatic, using the same hardened generator the dashboard uses. Every product whose `delivery` is `lines` on [products](https://hproxy.com/docs/proxy-api/products) generates (residential, mobile, ISP rotating, IPv4 and IPv6 per GB); the product's `generate` block, and each plan's, says which targeting fields its network takes. Lines come back as `host:port:username:password` with the targeting baked into the username, so any client that accepts a proxy username and password uses them without extra settings. Chrome and other Chromium browsers never send a SOCKS5 username and password, so for them generate with `protocol` set to `http`, the default. Every field is optional; an empty body returns one rotating line with the plan's defaults. Generating lines is free and repeatable: traffic is only consumed when the lines are used. All generated lines draw from the SAME plan balance. Dedicated per-IP products don't generate; fetch them from [GET /proxies](https://hproxy.com/docs/proxy-api/proxies) instead.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `protocol` | `string` | optional | "http" (default) or "socks5". |
| `count` | `integer` | optional | Lines to return, 1 to 5000, and at most the plan's own `generate.maxCount` (5,000 on Residential Premium, 1,000 on Residential Lite); a count past it answers 400 `invalid_count` naming the ceiling. Default 1. Sticky and rotating batches share this limit: on Residential Premium sticky lines take the sticky ports in turn and every line holds its own session, so the number of ports never limits a batch. Each plan's `generate.sticky` block carries the sticky port range (`port`, `ports`). |
| `country` | `string` | optional | Country targeting, e.g. "US" (letters only, 2 to 40 chars). This is where a residential order gets its country: the order carries none, so one plan serves every country and each call can target a different one. |
| `state` | `string` | optional | State / region targeting, where the pool supports it. |
| `city` | `string` | optional | City targeting, where the pool supports it. |
| `isp` | `string` | optional | ISP targeting by name. Residential Plus plans only (400 on other products). |
| `asn` | `integer` | optional | ISP targeting by AS number, e.g. 7018 for AT&T or 7922 for Comcast, together with `country`. Residential Premium plans only; the list per country is `GET /v1/products/residential-premium/geo/asns?country=US`. 400 on other products. |
| `os` | `string` | optional | "windows", "android", "ios" or "mac": the device the exit IP belongs to. Residential Premium only. |
| `strict` | `boolean` | optional | Default true: a target with no IP free fails the request. false: the gateway hands out another IP from the same country instead. Residential Premium only. |
| `excludeAsn` | `integer[]` | optional | Up to 20 AS numbers to avoid. Not together with `excludeCountries`. Residential Premium only. |
| `excludeCountries` | `string[]` | optional | Up to 20 two-letter country codes to avoid; only without `country`. Residential Premium only. One exclusion kind per call: countries, states, cities or networks, never two. |
| `excludeStates` | `string[]` | optional | Up to 20 state / region names to avoid inside `country` (e.g. ["California", "Texas"]); not together with a `state` target. Residential Premium only. |
| `excludeCities` | `string[]` | optional | Up to 20 city names to avoid inside `country` (e.g. ["New York", "Houston"]); not together with a `city` target. Residential Premium only. |
| `udp` | `boolean` | optional | `true` lets a `socks5` line open UDP relays (SOCKS5 UDP ASSOCIATE). Refused on `http`. Residential Premium only. |
| `stickyMinutes` | `integer` | optional | Turns sticky on. Omit for rotating IPs. On Residential Premium the number is the session length in minutes, 3 to 1440 (24 hours), and each sticky line holds its own session with no limit on how many; on Plus it is the session length up to 24 hours. On Residential Lite the pool takes no duration, so any value above 0 simply turns sticky on and the session lasts as long as you keep reusing the line. Each plan's `generate` block reports its own `minStickyMinutes` / `maxStickyMinutes`. |

**Request**

```bash
curl -X POST https://hproxy.com/api/v1/plans/cmjfmhhpd004c4i4hqsk3mzrr/generate \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"count": 3, "country": "US", "stickyMinutes": 30}'
```

**Response**

```json
{
  "lines": [
    "203.0.113.10:10000:hp_x92kf-us-sess-a8x2q-t-30:9f2a1c7b",
    "203.0.113.10:10000:hp_x92kf-us-sess-k3m7d-t-30:9f2a1c7b",
    "203.0.113.10:10000:hp_x92kf-us-sess-p5r1w-t-30:9f2a1c7b"
  ],
  "productId": "residential-premium"
}
```

Ownership is strict: the plan must be **yours** and **active**, anything else is a plain `404` (an id never confirms another account's plan exists). Free-text targeting is validated before it touches the network (letters, digits, spaces and simple punctuation only), so a bad value is a clean `400` naming the rule. The exact host, port and username grammar in the response varies by pool; treat lines as opaque and use them verbatim.

### Rotating vs sticky sessions

This is the one choice that shapes how a line behaves, and it is just whether you send `stickyMinutes`:

*Mode*

| Field | Type | Description |
| --- | --- | --- |
| `Rotating (default)` | `omit stickyMinutes` | Every request through the line can exit from a different residential IP. Best for scraping, wide coverage, and spreading load. Ask for `count: N` and you get N interchangeable rotating lines. |
| `Sticky` | `stickyMinutes: N` | The line holds the SAME exit IP instead of rotating per request. Best for anything that needs a stable identity across several requests: a login, a cart, a session. Each line you generate gets its OWN sticky session, so `count: 10` with stickyMinutes gives ten simultaneous stable identities. How long it holds depends on the product: Residential Premium and Plus take the duration you ask for, while Residential Lite holds the address for as long as you keep using the line and takes no duration. The address can still change early on any product if that particular device leaves the network, so write a retry either way. |

**Generation is free, instant and repeatable, and it reveals nothing new.** A plan has ONE credential pair; every line is that same pair with the country and session written into the username, so calling generate again just hands back more lines against the same balance. Nothing is 'used up' until traffic actually flows. So a storefront can safely let a customer regenerate lines whenever they want (roll a fresh IP, retarget a country) without spending anything. Data is metered only by bytes through the proxy, drawn from the plan's GB, and you can read what is left any time from [GET /plans/{id}](#plan-get) or be [pushed `plan.low_traffic`](https://hproxy.com/docs/proxy-api/webhooks) at 10%. Generate when you need lines rather than storing them: the pair inside a line can rotate when we move a pool, while the plan id and its balance stay the same.

> [!TIP] Building a reseller integration? The [reselling guide](https://hproxy.com/docs/proxy-api/reselling) walks the whole loop, and the [Reseller API](https://hproxy.com/docs/proxy-api/reseller) does the same generation **as each of your customers** so every line is billed and isolated per customer.

## Your dedicated proxies

*GET /api/v1/proxies lists the dedicated IPv4, IPv6, ISP and mobile proxies a key owns, credentials included. Filter by family or by the order that delivered them.*

URL: https://hproxy.com/docs/proxy-api/proxies

#### GET /api/v1/proxies

**List your proxies.** Every **dedicated** proxy the account owns (IPv4, IPv6, ISP, Mobile), with connection credentials: the delivery step after a per-IP purchase. Served from a local mirror, so it's instant and keeps working through upstream turbulence: new purchases appear right after the order fulfills, everything else refreshes within ~30 minutes. Filter `order_id` with the id `POST /orders` returned to fetch exactly that order's proxies. Each proxy's `id` is what a [renewal](https://hproxy.com/docs/proxy-api/orders#orders-create) references in `fulfillment_meta.ids`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `family` | `string (query)` | optional | "ipv4", "ipv6", "isp" or "mobile". Omitted = all. |
| `order_id` | `string (query)` | optional | Only the proxies delivered by this order (ord_…). |
| `include_inactive` | `boolean (query)` | optional | true to include expired/retired proxies. Default: active only. |
| `limit` | `integer (query)` | optional | Max rows. Default 1000, max 5000. |

**Request**

```bash
curl "https://hproxy.com/api/v1/proxies?family=ipv4&order_id=ord_8f49...8821" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "count": 2,
  "proxies": [
    {
      "active": true,
      "country": "US",
      "expiresAt": "2026-08-22",
      "family": "ipv4",
      "id": "9214321",
      "ip": "203.0.113.7",
      "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821",
      "password": "d41f9c2a",
      "portHttp": 10090,
      "portSocks": 11090,
      "protocols": ["http", "socks5"],
      "username": "hp_k29dj"
    },
    {
      "active": true,
      "country": "US",
      "expiresAt": "2026-08-22",
      "family": "ipv4",
      "id": "9214322",
      "ip": "203.0.113.8",
      "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821",
      "password": "d41f9c2a",
      "portHttp": 10090,
      "portSocks": 11090,
      "protocols": ["http", "socks5"],
      "username": "hp_k29dj"
    }
  ]
}
```

Fields the record doesn't state are `null`, never invented. A proxy that expired or was retired flips to `active: false` (hidden unless `include_inactive=true`). History is kept, nothing silently disappears. Gateway plans (residential, mobile, ISP rotating, IPv4 and IPv6 per GB) don't live here: their lines are generated on demand from [Plans & generation](https://hproxy.com/docs/proxy-api/plans#generate).

> [!NOTE] A freshly fulfilled order's proxies appear within seconds. If you get an empty list right after `POST /orders`, poll [GET /orders/{id}](https://hproxy.com/docs/proxy-api/orders#orders-get) until it's `completed`, or skip polling entirely with a [webhook](https://hproxy.com/docs/proxy-api/webhooks).

## Webhooks

*Register an HTTPS endpoint and get pushed order.fulfilled, order.failed, order.refunded and subscription events, HMAC-SHA256 signed, instead of polling.*

URL: https://hproxy.com/docs/proxy-api/webhooks

Stop polling. Register an HTTPS endpoint and we **push** you a signed JSON event the moment an order or subscription reaches a terminal state. Deliveries are HMAC-SHA256 signed, retried with backoff for hours, and idempotently enqueued (one event per endpoint per resource), so treat them as at-least-once and de-duplicate on `(event, data.orderId)`.

#### POST /api/v1/webhooks

**Register an endpoint.** Register an **https** URL for event pushes. The response carries your signing `secret` **once**. Store it now, it is never shown again. `events` defaults to everything; up to 10 active endpoints per account. Private/internal hosts are refused at registration.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | required | HTTPS endpoint to receive signed event POSTs. |
| `events` | `string[]` | optional | Subset of: order.fulfilled, order.failed, order.refunded, subscription.canceled, subscription.expired, plan.low_traffic, announcement.published. Omitted = all. |

**Request**

```bash
curl -X POST https://hproxy.com/api/v1/webhooks \
  -H "X-API-Key: hpx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.your-shop.com/hproxy-webhook", "events": ["order.fulfilled", "order.failed"]}'
```

**201 Created**

```json
{
  "active": true,
  "createdAt": "2026-07-23T09:15:02.114Z",
  "events": ["order.fulfilled", "order.failed"],
  "id": "whs_1f7c9a2b8d3e4f50a1b2c3d4e5f60718",
  "secret": "whsec_9a1b…store-me-now…7f2e",
  "url": "https://api.your-shop.com/hproxy-webhook"
}
```

#### GET /api/v1/webhooks

**List endpoints.** Your registered endpoints, newest first. Secrets are never re-shown.

**Request**

```bash
curl https://hproxy.com/api/v1/webhooks -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "webhooks": [
    {
      "active": true,
      "createdAt": "2026-07-23T09:15:02.114Z",
      "events": ["order.fulfilled", "order.failed"],
      "id": "whs_1f7c9a2b8d3e4f50a1b2c3d4e5f60718",
      "url": "https://api.your-shop.com/hproxy-webhook"
    }
  ]
}
```

#### DELETE /api/v1/webhooks/{id}

**Delete an endpoint.** Remove an endpoint; its pending deliveries go with it.

**Request**

```bash
curl -X DELETE https://hproxy.com/api/v1/webhooks/whs_1f7c9a2b8d3e4f50a1b2c3d4e5f60718 \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{ "deleted": true }
```

#### POST /api/v1/webhooks/{id}/test

**Send a test delivery.** Queues a `ping` event through the **real** pipeline (same signing, same worker) so you can verify your endpoint and signature code end to end. Expect the POST within about a minute.

**Request**

```bash
curl -X POST https://hproxy.com/api/v1/webhooks/whs_1f7c9a2b8d3e4f50a1b2c3d4e5f60718/test \
  -H "X-API-Key: hpx_your_key_here"
```

**202 Accepted**

```json
{ "queued": true, "event": "ping" }
```

### What a delivery looks like

Every delivery is a `POST` with `Content-Type: application/json` and three headers: `X-HProxy-Event` (the event type), `X-HProxy-Signature` (hex HMAC-SHA256 of the raw body) and `X-HProxy-Timestamp` (a convenience mirror. The tamper-proof time is `created` **inside** the signed body). Order events carry the same public vocabulary as `GET /orders/{id}`, so your handler and your poller read identical statuses.

**Delivery body**

```json
{
  "event": "order.fulfilled",
  "created": "2026-07-23T09:16:41.220Z",
  "resource": "order",
  "data": {
    "orderId": "ord_8f491789-58cd-4e82-81a2-ec7c28088821",
    "status": "completed",
    "productId": "ipv4",
    "quantity": 5,
    "amountCents": 1050,
    "currency": "USD",
    "createdAt": "2026-07-23T09:15:12.003Z",
    "fulfilledAt": "2026-07-23T09:16:38.551Z"
  }
}
```

### Plan events: know when a customer runs low

`plan.low_traffic` fires when an active GB plan drops to **10% or less** of its total: the signal a reseller uses to prompt their customer to top up. It carries the plan snapshot including your [label](https://hproxy.com/docs/proxy-api/plans#plan-label), so the alert is already attributed to your customer. It fires **once per plan per endpoint** (a top-up does not re-arm it), and a newly registered endpoint receives one event per plan that is already low at that moment.

**plan.low_traffic delivery**

```json
{
  "event": "plan.low_traffic",
  "created": "2026-07-23T02:01:00.412Z",
  "resource": "plan",
  "data": {
    "planId": "cmjfmhhpd004c4i4hqsk3mzrr",
    "label": "customer-1042",
    "product": "residential-premium",
    "dataGbTotal": 10.0,
    "dataGbRemaining": 0.8,
    "thresholdPct": 10,
    "expiresAt": null
  }
}
```

### Service notices: know when we change something

`announcement.published` fires when we publish a [service notice](https://hproxy.com/docs/announcements): a maintenance window, an incident, a pricing change, or an `ACTION_REQUIRED` notice about the API itself. It carries the id, title, kind and audience; read the body from [GET /announcements](https://hproxy.com/docs/announcements) when you need it. Only notices addressed to an audience your account belongs to are delivered, and every account with a key belongs to `DEVELOPERS`.

**announcement.published delivery**

```json
{
  "event": "announcement.published",
  "created": "2026-09-03T18:40:12.101Z",
  "resource": "announcement",
  "data": {
    "announcementId": "1f3c9a7e-…",
    "title": "Order bodies are now strict: unknown fields return 400",
    "kind": "ACTION_REQUIRED",
    "audience": "DEVELOPERS"
  }
}
```

### Verifying the signature

Compute HMAC-SHA256 of the **exact raw request body bytes** with your `whsec_…` secret and compare it (constant-time) to `X-HProxy-Signature`. We sign the exact bytes we send, so there is nothing to re-serialize. Respond `2xx` to acknowledge; anything else is retried with exponential backoff (first retry ~30s, doubling, capped at 6h) for up to 10 attempts.

**Node.js**

```js
import crypto from "crypto";

export function verifyHproxySignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret)
    .update(rawBody) // the EXACT raw bytes, before any JSON.parse
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}
```

**Python**

```python
import hashlib, hmac

def verify_hproxy_signature(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)
```

> [!WARNING] **Verify before you trust**: Parse the body ONLY after the signature checks out, and reject events whose `created` is older than your replay window (5 minutes is a good default).

## Build a reseller business on HProxy

*The reseller loop over the HProxy API: fund a wallet, sell residential GB or dedicated IPs, deliver programmatically, get pushed on fulfillment and renew.*

URL: https://hproxy.com/docs/proxy-api/reselling

Everything a proxy storefront needs, over one API: **prepaid wallet**, **server-authoritative quotes**, **idempotent orders**, **programmatic delivery** for both residential lines and dedicated IPs, **webhooks** on fulfillment, and **renewals**. Your customers never see HProxy: every response is white-label by construction.

1. **Fund the wallet**: `POST /deposits` returns a hosted `payUrl` (card or crypto). Everything below prepays from this balance and fails with an honest `402` when it's short. No surprise card charges, ever.
2. **Quote before you sell**: `GET /products/{id}/price` returns the exact amount the order will charge. For dedicated IPs pass `country` and `period_days` too. Put your margin on top and show YOUR price.
3. **Buy on demand**: `POST /orders` with an `Idempotency-Key`. Wallet-paid orders return in seconds; a retry with the same key can never double-charge. For residential the body is `product_id` plus `quantity` in GB and nothing else: the country is chosen in the next step.
4. **Deliver**: Residential: `POST /plans/{id}/generate` per customer request. Dedicated: `GET /proxies?order_id=…` once the order completes.
5. **Attribute**: `PATCH /plans/{id}` with a `label`. Your reference rides on every read and every webhook for that plan after that.
6. **Get pushed, don't poll**: Register a [webhook](https://hproxy.com/docs/proxy-api/webhooks): `order.fulfilled` fulfills the sale, `plan.low_traffic` prompts the top-up.
7. **Renew**: `POST /orders` with `fulfillment_meta: {"kind": "extension", "ids": […]}` renews exactly the proxies your customer keeps.

### Selling residential GB: how plans work

**One account holds one active plan per residential product, and every purchase tops it up.** Buy 5 GB of `residential-lite`, then 3 GB more, and you have one plan with 8 GB, one credential pair and one balance. Generation is free and repeatable: every line you generate is that same credential with the country and session written into the username, and the plan's GB is drawn down only by the traffic that actually flows. There is no per-line metering, so lines you hand to different people share one balance.

That is the right shape for **your own usage, trials and burst capacity**, and the wrong shape for selling to more than one customer: whoever generates lines first can spend the other's traffic, and nothing in this lane can stop them. **Isolation per customer is the Reseller API**, described below: one header names your customer, and the call runs as an account of their own, with its own plan, its own credentials, its own GB cap and its own balance. That is the sub-user model, and it is the lane a storefront should be on before its second customer.

**Residential loop, single account**

```bash
# The single-account loop: your own usage, or one trial pool.
# 1. Buy 10 GB. A later purchase of the same product tops up this plan.
curl -X POST https://hproxy.com/api/v1/orders \
  -H "X-API-Key: hpx_your_key_here" -H "Idempotency-Key: pool-resi-10gb" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "residential-lite", "quantity": 10}'

# 2. Your plan (one per residential product), with its remaining GB
curl https://hproxy.com/api/v1/plans -H "X-API-Key: hpx_your_key_here"

# 3. Tag it with your own reference
curl -X PATCH https://hproxy.com/api/v1/plans/{planId} \
  -H "X-API-Key: hpx_your_key_here" -H "Content-Type: application/json" \
  -d '{"label": "trial-pool"}'

# 4. Generate lines (free, repeatable; GB is spent by traffic only)
curl -X POST https://hproxy.com/api/v1/plans/{planId}/generate \
  -H "X-API-Key: hpx_your_key_here" -H "Content-Type: application/json" \
  -d '{"count": 100, "country": "US", "stickyMinutes": 10}'

# 5. Read the balance any time (synced about every 30 minutes)
curl https://hproxy.com/api/v1/plans/{planId} -H "X-API-Key: hpx_your_key_here"
```

> [!NOTE] **Updated**: Updated 2026-09-03. An earlier version of this section described a per-purchase plan model that no longer applies: a purchase of a residential product tops up the plan you hold for it. If you built on the older wording, read plan ids from `GET /plans` after each order instead of expecting a new one, and use the Reseller API below for isolation per customer.

### Sub-users: one account per customer, over one header

On the Reseller API your key names a customer with `X-Reseller-Customer-Id`, and every call runs **as that customer**: `POST /orders` provisions their own plan and credentials, `GET /plans` lists only theirs, `GET /wallet` is the credit you issued them, and `GET /customers` is your whole book. Customer A can never generate from customer B's plan, because they are different accounts. Nothing else about the API changes. The lane is granted rather than self-served, and getting on it is four steps:

1. **Apply from your dashboard**: Sign in and open [Reseller](https://hproxy.com/dashboard/reseller): your business name, a few lines about what you sell, and the Partner Agreement. The application is tied to the account whose key you already use, so there is nothing to re-create.
2. **We review it, in person**: Every partner is onboarded by a person, the founder included. We reply on the email of your account and ask for a Telegram or WhatsApp contact, so you have a direct line for the whole time you sell on the platform.
3. **Approval provisions the lane**: Your account gets a rate card and a business dashboard (balance, customers, your prices, statement, support inbox). In the dashboard, under Storefront, API access, you create your reseller API key yourself: it carries the `act_as_reseller_customer` scope, it is shown once, and it is the key that names customers. The key you have today keeps working for your own account.
4. **Put customers behind the header**: Add `X-Reseller-Customer-Id: <your id for them>` to any call. The first call creates the customer; `PUT /customer/contact` attaches their email and a display name; an order as them provisions their own plan. The full loop is on the [Reseller API](https://hproxy.com/docs/proxy-api/reseller) page.

### Selling dedicated IPs (IPv4 / IPv6 / ISP / Mobile)

**Dedicated loop**

```bash
# 0. Show your customer the countries in stock right now (name + alpha3),
#    plus the rental periods. Always current: sold-out countries drop out.
curl https://hproxy.com/api/v1/products/ipv4/options -H "X-API-Key: hpx_your_key_here"

# 1. Quote the exact charge for the targeting your customer picked
curl "https://hproxy.com/api/v1/products/ipv4/price?quantity=5&country=DEU&period_days=30" \
  -H "X-API-Key: hpx_your_key_here"

# 2. Buy with the same targeting
curl -X POST https://hproxy.com/api/v1/orders \
  -H "X-API-Key: hpx_your_key_here" -H "Idempotency-Key: cust-1042-ipv4-de-5" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "ipv4", "quantity": 5,
       "fulfillment_meta": {"country": "DEU", "period_days": 30}}'

# 3. On the order.fulfilled webhook (or once GET /orders/{id} says completed):
curl "https://hproxy.com/api/v1/proxies?order_id={orderId}" -H "X-API-Key: hpx_your_key_here"
# -> ip, ports, username, password per proxy. Hand them to your customer.

# 4. Renewal, 30 more days for the proxies the customer kept
curl -X POST https://hproxy.com/api/v1/orders \
  -H "X-API-Key: hpx_your_key_here" -H "Idempotency-Key: cust-1042-renew-jul" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "ipv4", "quantity": 2,
       "fulfillment_meta": {"kind": "extension", "ids": ["9214321", "9214322"], "period_days": 30}}'
```

Renewals are ownership-checked server-side: the `ids` (from [GET /proxies](https://hproxy.com/docs/proxy-api/proxies)) must belong to the calling account, and the renewal is priced for exactly those proxies. `quantity` should match the number of ids.

### Selling scrapers

A scraper call is charged to your own balance at our normal per-call price, the same as for every customer, whether you call it for yourself or for a customer of yours. Put your own price on top in your billing. The [Scraper API](https://hproxy.com/docs/scrapers) pages list every endpoint and its price.

> [!WARNING] **Scrapers change often**: A scraper reads a website we do not control. When that website changes its pages, its limits or how it blocks automated traffic, a scraper can fail, return fewer fields, or return fields in a different shape until we update it, and we update scrapers often. **Scrapers are not a stable product that never breaks.** Handle errors and retry, read the fields inside `data` defensively, subscribe to [service notices](https://hproxy.com/docs/announcements), and do not promise your customers that a scraper will never change or never fail. The envelope around `data` keeps its shape.

### What stays stable when we change things underneath

The networks behind a product change, sometimes at short notice, and a storefront should never notice. Build on the things we keep stable and treat everything else as a value to read, not to remember:

1. **Product ids**: `residential-lite`, `residential-premium`, `ipv4` and the rest are ours and stay put when the pool behind them is swapped. Read `GET /products` for `available` and the targeting contract instead of hardcoding either.
2. **Plan ids and balances**: A plan id never changes meaning: the plan keeps serving its remaining gigabytes from the pool it was bought on. When we move a product to a new pool, the next purchase of that product opens a fresh plan beside the old one, so for a while `GET /plans` can list two plans for one product. List plans and read their balances rather than assuming one per product, and read plan ids from the API after an order completes rather than predicting them.
3. **Lines, generated on demand**: Generate through `POST /plans/{id}/generate` when a customer needs lines, and hand those out. The credentials inside a line can rotate when a pool moves, so do not store lines for longer than a session or bake them into a customer's config.
4. **Order and proxy ids**: Renewals and lookups run on our ids (`orderId`, the `id` in `GET /proxies`), never on anything that names a network.
5. **Notices**: A change that needs something from you arrives as an `ACTION_REQUIRED` [service notice](https://hproxy.com/docs/announcements): in the feed, as the `announcement.published` webhook, and by email to the account. Subscribe once and you will not learn about a change from a failing request.

Our side of it: fields and codes are only ever added, never renamed or removed, and an existing `code` keeps its meaning. If a call ever has to change how it behaves, the change is announced as an `ACTION_REQUIRED` notice with a date before it happens, and the old behavior keeps working until that date. Nothing in a response names a network or a provider, so a pool change is not something your code can see.

### Safety rails for production

Send an `Idempotency-Key` on every write, so retries converge instead of double-charging. Put a **daily spend cap** on the key in your dashboard, so a leak can't drain the wallet. Verify [webhook signatures](https://hproxy.com/docs/proxy-api/webhooks) before trusting a delivery. Branch on the machine `code` in error bodies (`402` = top up, `429` = back off per `Retry-After`). And generate your client from the [OpenAPI spec](https://hproxy.com/docs/openapi) instead of hand-writing one.

> [!NOTE] **White-label by construction**: Responses never name upstream networks or infrastructure partners, so your storefront stays fully white-label.

> [!TIP] **The sub-user lane**: Selling to more than one customer? Apply for the [Reseller API](https://hproxy.com/docs/proxy-api/reseller) from your [dashboard](https://hproxy.com/dashboard/reseller): one account per customer, isolated plans and balances, your negotiated rates, and a customer book with names and emails.

## Reseller API: act as your customers

*For approved resellers: name each of your customers with X-Reseller-Customer-Id and every call runs as them: isolated plans and balances per customer, orders at your negotiated rates, and a customer book with contact identity.*

URL: https://hproxy.com/docs/proxy-api/reseller

The reselling guide's loop runs everything through YOUR account and tags plans with labels. **Approved resellers get a stronger model**: your key names one of your customers per request, and the call runs **as that customer**: their own plans, their own spendable balance, their own order history, fully isolated from every other customer. You price in your business dashboard, we charge you your negotiated rates, and your customers never see us anywhere.

Reseller access is granted, not self-served. Apply from [Reseller in your dashboard](https://hproxy.com/dashboard/reseller) with the account whose key you already use; we review every application in person and reply on the account's email. Approval provisions your rate card and opens your business dashboard (balance, statement, customers, your prices, storefront, support inbox). Your reseller API key, carrying the `act_as_reseller_customer` scope, is one you create in that dashboard under Storefront, API access; it is shown once, and you can hold up to three and revoke any of them there. The [reselling guide](https://hproxy.com/docs/proxy-api/reselling#sub-users-one-account-per-customer-over-one-header) walks the four steps.

### Naming a customer

Add one header to any `/api/v1` call. The id is **yours** (your user id, an email hash, anything stable): up to 64 characters of letters, digits, `_`, `-`, `.`. It is scoped to your account, so two businesses using the same id refer to different people and can never see each other's data. **The customer is created the first time you name one**, so there is no signup call.

**Any call, as your customer**

```bash
curl https://hproxy.com/api/v1/plans \
  -H "X-API-Key: hpx_your_key_here" \
  -H "X-Reseller-Customer-Id: user-4021"
```

Without the header, the same key acts as your own account (your wallet, your deposits), which is how you top up your reseller balance. With it, reads and writes belong to that customer.

### Do I need to set up CORS?

**No.** CORS is a rule browsers apply to web pages, and your reseller key belongs on your **server**, never in your site's JavaScript: a key in the browser can be copied by any visitor and spent against your balance. Server-to-server calls (your backend calling ours) are not subject to CORS at all, so there is nothing to configure on your side or ours. Your customers' browsers talk to **your** site; your site's backend calls `/api/v1`.

For completeness: `/api/v1` does answer browser preflights from any origin and accepts `X-API-Key`, `Authorization`, `X-Reseller-Customer-Id`, `Idempotency-Key` and `Content-Type`, which is what our own browser extension relies on. It sends no cookies and reads none, so opening it to every origin gives nobody access they would not have with your key anyway.

Optional hardening: in your business dashboard under **API keys**, **Lock your keys to your servers** lets you list the IP addresses your backend calls from. Your keys then stop working from anywhere else, so a leaked copy is useless.

### How the money works

Your customers pay **you**, on your site, with your payment methods. You mirror what they paid you as **store credit** on that customer (from your business dashboard, or from your own backend with [`PUT /customer/credit`](#partner-customer-credit)), and their orders spend that credit at **your prices** while your prepaid reseller balance is charged **your negotiated rate** in the same transaction. The gap is your margin, and it never appears in anything their side can read. When their credit is short an order fails with `402 customer_credit_insufficient`; when your balance is short, `402 reseller_balance_insufficient`. Nothing half-charges. Your storefront can also take the payment itself: connect your **own** gateway (Heleket or NOWPayments for crypto, Stripe or Payoneer Checkout for cards) under Payments in your business dashboard, and [`POST /deposits`](#partner-deposit-create) for a named customer returns a pay page on **your** merchant account. What arrives is credited to that customer automatically, underpayments and overpayments included. Without a gateway for the requested method the call answers `403 deposits_not_available`; there is never a payment page of ours for your customers to reach.

#### GET /api/v1/customer

**Read the acting customer.** The named customer's profile: your id for them, your display name (`label`), the email you attached, the credit they can still spend (in cents, at your prices), and when they were created and last seen. Requires the `X-Reseller-Customer-Id` header.

**Request**

```bash
curl https://hproxy.com/api/v1/customer \
  -H "X-API-Key: hpx_your_key_here" \
  -H "X-Reseller-Customer-Id: user-4021"
```

**Response**

```json
{
  "customer": {
    "externalId": "user-4021",
    "label": "Alex M.",
    "contactEmail": "alex@example.com",
    "creditCents": 2500,
    "createdAt": "2026-08-23T15:02:11+00:00",
    "lastSeenAt": "2026-08-23T16:40:03+00:00"
  }
}
```

#### PUT /api/v1/customer/contact

**Attach their identity.** Set the customer's email and your display name for them, ideally right after your own signup flow, so your customer book, your business dashboard and our support all see a person instead of an opaque id. Each field: **omitted = unchanged, empty string = cleared, value = set**. We never send mail to this address; it is identity, not a channel.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | `string` | optional | The customer's email address. Stored lowercased. Empty string clears it. |
| `label` | `string` | optional | Your display name for them, 1 to 120 characters. Empty string clears it. |

**Request**

```bash
curl -X PUT https://hproxy.com/api/v1/customer/contact \
  -H "X-API-Key: hpx_your_key_here" \
  -H "X-Reseller-Customer-Id: user-4021" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex@example.com", "label": "Alex M."}'
```

**Response**

```json
{
  "customer": {
    "externalId": "user-4021",
    "label": "Alex M.",
    "contactEmail": "alex@example.com",
    "creditCents": 2500,
    "createdAt": "2026-08-23T15:02:11+00:00",
    "lastSeenAt": "2026-08-23T16:40:03+00:00"
  }
}
```

#### PUT /api/v1/customer/credit

**Credit or revoke their balance.** Move store credit on the named customer, from your own backend: **grant** when they paid you, **revoke** for a refund on your side or a correction. Amounts are whole cents at your retail prices; one movement is at most $5,000. Send your own `request_id` for every movement (your payment id, your refund id): a repeat with the same id answers `409 already_applied` instead of moving the credit twice, so a retry is always safe. A revoke larger than what is left is refused (`revoke_exceeds_credit`) and names the remaining figure. Requires the `X-Reseller-Customer-Id` header.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_cents` | `integer` | required | Positive whole cents at your prices. |
| `direction` | `string` | required | "grant" or "revoke". |
| `request_id` | `string` | required | Your id for this movement, one per intent, 1 to 100 characters. |
| `note` | `string` | optional | Shown on your statement, up to 200 characters. |

**Request**

```bash
curl -X PUT https://hproxy.com/api/v1/customer/credit \
  -H "X-API-Key: hpx_your_key_here" \
  -H "X-Reseller-Customer-Id: user-4021" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 2500, "direction": "grant", "request_id": "pay_8f3a21", "note": "Stripe pi_3Q…"}'
```

**Response**

```json
{
  "customer": {
    "externalId": "user-4021",
    "label": "Alex M.",
    "contactEmail": "alex@example.com",
    "creditCents": 5000,
    "createdAt": "2026-08-23T15:02:11+00:00",
    "lastSeenAt": "2026-08-23T16:40:03+00:00"
  }
}
```

#### POST /api/v1/deposits

**Let the named customer pay you.** With `X-Reseller-Customer-Id`, this creates an invoice on **your own** payment gateway (connected under Payments in your business dashboard) and returns its pay page: crypto through Heleket or NOWPayments (`method: "crypto"`), cards through Stripe Checkout or Payoneer Checkout (`method: "card"`); one live gateway per rail. The page shows your merchant name, the money goes to your account, and when it arrives we credit the customer's store credit automatically: the exact amount, the whole amount when they overpay, and what actually arrived when a crypto invoice closes short. Amounts are whole cents; sub-floor amounts are raised to the method floor ($3 crypto, $10 card) and one invoice is at most $5,000. Send an `Idempotency-Key` and a retried request returns the same open invoice. No gateway for that method ⇒ `403 deposits_not_available`.

**An order can pay for itself.** [`POST /orders`](https://hproxy.com/docs/proxy-api/orders) for a named customer with `method: "crypto"` or `"card"` and short credit still answers `402 customer_credit_insufficient`, but with `payUrl`, `depositId`, `chargeCents` (the shortfall raised to the rail's minimum) and `shortfallCents` added. Send the customer to `payUrl`: when the money lands, the credit is granted and the order is placed automatically under the same `Idempotency-Key`, a Telegram customer is told in the store's bot, and [`GET /deposits/{id}`](#partner-deposit-get) shows `for_order: true`. Without a gateway for that rail the 402 carries no pay page and the customer needs credit first.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_cents` | `integer` | required | Whole cents at your prices. |
| `method` | `string` | optional | "crypto" or "card". Default "card". |
| `return_url` | `string` | optional | Where the customer lands after paying (https). Default: your website, else your Telegram storefront. |

**Request**

```bash
curl -X POST https://hproxy.com/api/v1/deposits \
  -H "X-API-Key: hpx_your_key_here" \
  -H "X-Reseller-Customer-Id: user-4021" \
  -H "Idempotency-Key: topup_8f3a21" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 2500, "method": "crypto", "return_url": "https://shop.example.com/wallet"}'
```

**Response**

```json
{
  "deposit_id": "rpay_cmt9x2k1a0001",
  "pay_url": "https://pay.heleket.com/pay/4f1c…",
  "amount_cents": 2500,
  "status": "awaiting_payment"
}
```

#### GET /api/v1/deposits/{id}

**Read one of your customers' payments.** The state of a deposit your storefront created, for your own backend to show "payment received". `status` is `awaiting_payment`, `paid`, `paid_over`, `underpaid`, `expired`, `cancelled`, `failed`, `locked` (held by the gateway; nothing credited) or `needs_review`. `credited_cents` is what landed on the customer's store credit. Account-level: no customer header needed, and only your own deposits resolve.

**Request**

```bash
curl https://hproxy.com/api/v1/deposits/rpay_cmt9x2k1a0001 \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "deposit_id": "rpay_cmt9x2k1a0001",
  "status": "paid",
  "provider": "heleket",
  "method": "crypto",
  "amount_cents": 2500,
  "received_cents": 2500,
  "credited_cents": 2500,
  "pay_url": null,
  "created_at": "2026-09-04T09:12:41+00:00",
  "settled_at": "2026-09-04T09:20:03+00:00"
}
```

#### GET /api/v1/usage

**A customer's bandwidth history.** With `X-Reseller-Customer-Id`, the named customer's traffic from the meter: one row per day and one per plan over the last `days` days (1 to 365, default 30). `gbUsed` is what was consumed that day; `null` means no reading exists for that day (a plan's first day, or a gap) and is never zero, and `unknownDays` counts those. Each day also carries `gbTotal` (the caps of the plans measured that day) and `gbLeft` (what they still held at the day's last reading), so how much a customer had and how much is left is a history, not a snapshot. Each plan line carries its cap, the meter at the last reading (`gbUsedEnd`) and `gbLeft`. Narrow to one plan with `plan_id`. What they bought is on [`GET /orders`](https://hproxy.com/docs/proxy-api/orders); this is what they used. Readings land every 30 minutes, one pass after the plan's own figures are synced, so a plan bought in the last hour may have no row yet; for a live figure read the plan itself (`GET /plans/{id}`).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `days` | `integer (query)` | optional | Window in days, 1 to 365. Default 30. |
| `plan_id` | `string (query)` | optional | One plan only. |

**Request**

```bash
curl "https://hproxy.com/api/v1/usage?days=7" \
  -H "X-API-Key: hpx_your_key_here" \
  -H "X-Reseller-Customer-Id: user-4021"
```

**Response**

```json
{
  "days": 7,
  "gbUsed": 3.42,
  "unknownDays": 1,
  "daily": [
    { "day": "2026-09-01", "gbUsed": null, "gbTotal": 10, "gbLeft": 9.1, "plans": 1, "unknown": 1, "meterResets": 0 },
    { "day": "2026-09-02", "gbUsed": 1.2, "gbTotal": 10, "gbLeft": 7.9, "plans": 1, "unknown": 0, "meterResets": 0 }
  ],
  "plans": [
    { "planId": "plan_…", "product": "residential-premium", "productName": "Residential Premium", "label": null,
      "gbUsed": 3.42, "daysKnown": 6, "unknownDays": 1, "gbTotal": 10, "gbUsedEnd": 4.3, "gbLeft": 5.7 }
  ]
}
```

#### GET /api/v1/store/usage

**Your whole store's bandwidth.** Account-level (no customer header): what all your customers used per day beside what you sold per day, per product, and the ten customers that used the most, over the last `days` days. `gb_used` is the meter, `gb_sold` is GB on paid orders by the day they were paid, `gb_total` and `gb_left` are what the measured plans had and still held at the day's last reading; the four are never mixed into one number. `unknown_days` counts plan-days without a reading. Readings land every 30 minutes, one pass after each plan's own figures are synced. Snake_case like the other account-level doors.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `days` | `integer (query)` | optional | Window in days, 1 to 365. Default 30. |

**Request**

```bash
curl "https://hproxy.com/api/v1/store/usage?days=30" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "days": 30,
  "totals": { "gb_used": 41.2, "gb_sold": 120, "gb_total": 300, "gb_left": 212.6, "unknown_days": 3, "plans": 17 },
  "daily": [ { "day": "2026-09-04", "gb_used": 1.4, "gb_total": 300, "gb_left": 212.6, "gb_sold": 10, "plans": 17, "unknown": 0, "meter_resets": 0 } ],
  "products": [ { "product": "residential-premium", "product_name": "Residential Premium", "gb_used": 30.1, "plans": 9, "unknown_days": 1, "gb_sold": 80, "orders": 12 } ],
  "customers": [ { "external_id": "user-4021", "label": "Ali", "gb_used": 14.2, "plans": 2 } ]
}
```

#### GET /api/v1/customers

**List your customers.** Every customer on your account, newest first, with identity and credit, the read your backend reconciles against. This is an **account-level** call: send it **without** the `X-Reseller-Customer-Id` header (naming a customer here is refused with a `400` telling you to drop the header).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `integer (query)` | optional | Page size, 1 to 200. Default 50. |
| `offset` | `integer (query)` | optional | Rows to skip. Default 0. |

**Request**

```bash
curl "https://hproxy.com/api/v1/customers?limit=50" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "customers": [
    {
      "externalId": "user-4021",
      "label": "Alex M.",
      "contactEmail": "alex@example.com",
      "creditCents": 2500,
      "createdAt": "2026-08-23T15:02:11+00:00",
      "lastSeenAt": "2026-08-23T16:40:03+00:00"
    },
    {
      "externalId": "user-3990",
      "label": null,
      "contactEmail": null,
      "creditCents": 0,
      "createdAt": "2026-08-22T10:11:40+00:00",
      "lastSeenAt": null
    }
  ]
}
```

### The whole loop, as one customer

**Signup to delivery**

```bash
# 0. Your customer signs up on YOUR site -> create + identify them
curl -X PUT https://hproxy.com/api/v1/customer/contact \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex@example.com", "label": "Alex M."}'

# 1. They paid you -> mirror it as credit, from your backend (or in the
#    business dashboard: Customers -> user-4021 -> Add credit)
curl -X PUT https://hproxy.com/api/v1/customer/credit \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents": 2500, "direction": "grant", "request_id": "pay_8f3a21"}'
# Their balance, any time:
curl https://hproxy.com/api/v1/wallet \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021"
# -> { "balanceCents": 2500, "currency": "USD" }  (their credit, your prices)

# 2. They buy on your site -> order AS them (Idempotency-Key is REQUIRED here).
#    Residential: product_id + quantity in whole GB, NO country. A 1 GB
#    package is "quantity": 1. The country comes in step 3.
curl -X POST https://hproxy.com/api/v1/orders \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \
  -H "Idempotency-Key: your-order-83741" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "residential-lite", "quantity": 5}'

# 3. Deliver: once GET /orders/{orderId} reads "completed" (or the
#    order.fulfilled webhook arrives), take the plan id from GET /plans and
#    generate lines from THEIR plan (free, repeatable). The country goes HERE.
curl https://hproxy.com/api/v1/plans \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021"
curl -X POST https://hproxy.com/api/v1/plans/{planId}/generate \
  -H "X-API-Key: hpx_your_key_here" -H "X-Reseller-Customer-Id: user-4021" \
  -H "Content-Type: application/json" \
  -d '{"count": 100, "country": "US", "stickyMinutes": 10}'
```

> [!NOTE] **Packages and countries**: A menu of **packages** (1 GB, 5 GB, 10 GB) is one product id ordered with different `quantity` values, never one id per package. `quantity` is a whole number of the product's unit from its `minQuantity`, so a residential package is at least 1 GB. The **country** is never part of a residential order: sell the GB, then generate lines for whichever country your customer picks, as often as they like, from the same plan.

Dedicated IPs work the same way: list the countries in stock with [`GET /products/{id}/options`](https://hproxy.com/docs/proxy-api/products#options) (always current, sold-out countries drop out on their own), quote and order with `country` and `period_days` in `fulfillment_meta` while naming the customer, then `GET /proxies?order_id=…` **as that customer** once the order completes. Renewals too: the `ids` must belong to the acting customer, exactly as ownership works everywhere else.

### Rules the lane enforces

**An `Idempotency-Key` is required on every reseller order** (a plain key merely should send one; a reseller key must, and an order without one is refused before any charge): only your system knows whether a request is a new sale or a retry, and this is what makes retries free. Isolation is structural: a customer id that is not yours simply does not resolve, plan and proxy ownership follow the acting customer, and `GET /plans` for customer A can never show customer B's plans. Reseller keys also carry a **higher rate-limit tier**, sized for a whole storefront (thousands of customers behind one key) rather than a single integration, so a busy shop or a bulk operation is never throttled for being busy.

> [!NOTE] **Your catalog**: On a reseller key, `GET /products` lists every product you can sell: the products sold per GB on your price list and, since September 15, 2026, dedicated IPs and ISP Unlimited too. It can include storefront-only products the public catalog does not list. Everything about them (pricing, options, ordering) works exactly like every other product on this page, and every quote on this key is at your prices. The other direction is yours too: a product you hide in your business dashboard (Pricing, then Hide) leaves your catalog and your bot on their next read, and an order for it as one of your customers answers `409 product_unavailable`.

### What you can sell, and what you pay

1. **Products sold per GB**: Residential Premium and Lite, IPv4 and IPv6 per GB, ISP Rotating and Mobile per GB each have **one fixed price per GB** on your price list (Pricing in your business dashboard), with your discount already in it when you have one. A single order never costs you more than our own customers pay for the same order.
2. **Dedicated IPs**: Static ISP, IPv4, IPv6 and mobile IPs are priced live per country and period. You pay **our customer price, less your discount** when you have one, and never below what the order costs us. Your customers pay our price times your markup, which you set per family in your business dashboard. **To see every price**, read [`GET /products/{id}/price-list?country=USA`](https://hproxy.com/docs/proxy-api/products#price-list): every period of the country with `yourCostCents` on each line. Your dashboard shows the same table under Pricing.
3. **ISP Unlimited**: `isp-unlimited` sells as a monthly speed tier: `quantity` is the tier in Mbps (10, 25, 50 or 100). You pay our tier price, less your discount when you have one; your customers pay it times your markup. Each order is its own plan: take its id from `GET /plans` and generate lines from it, as with residential.
4. **Scrapers**: A scraper call is charged to **your own balance** at our normal scraper price, the same as for every customer. Call scrapers with a reseller API key made from September 15, 2026, on (it carries the `scrape` scope) or with any key on your account that has that scope, and send them **without** `X-Reseller-Customer-Id`: naming a customer on a scraper call is refused with `400 drop_customer_header`. You bill your customers for scraper use yourself.

> [!WARNING] **Scrapers change often**: A scraper reads a website we do not control. When that website changes its pages, its limits or how it blocks automated traffic, a scraper can fail, return fewer fields, or return fields in a different shape until we update it, and we update scrapers often. **Scrapers are not a stable product that never breaks.** Handle errors and retry, read the fields inside `data` defensively, subscribe to [service notices](https://hproxy.com/docs/announcements), and do not promise your customers that a scraper will never change or never fail. The envelope around `data` keeps its shape.

> [!NOTE] **When your prices apply**: Your partner prices (your fixed prices, your discount) apply to orders placed **for one of your customers**: through your bot, or on the API with `X-Reseller-Customer-Id`. An order your key places with no customer named is bought for **your own account at our normal price**, without them. Every quote on your key says both figures: `yourCostCents` for your customers' orders, `listCents` for an order of your own.

### Lock your key to your servers

Your reseller key is a server-to-server credential, so you can pin it to the IP addresses your own backend calls us from. Set the allowlist in your business dashboard under **Storefront → Key access**, and the key stops working from anywhere else. A leaked copy is inert. It is off by default, holds a handful of IPv4/IPv6 addresses, and restricts **only the API key**: the dashboard is a separate, session-authed login, so a wrong entry locks your integration, never you out of fixing it. A call from a disallowed IP is refused with `403 ip_not_allowed`.

> [!TIP] **Where the rest lives**: Issue and revoke customer credit, set your prices, watch your statement and answer your customers' support messages in your business dashboard. The API is the selling lane; the dashboard is the business lane.

---

# Scraper API

## Scraper API

*Turn any supported platform into structured JSON with one call. 116 endpoints across 23 platforms, billed per successful call with exact fractional pricing.*

URL: https://hproxy.com/docs/scrapers

Turn any supported platform into structured JSON with one call. You send a small request, you get parsed JSON back in a stable envelope, plus the exact cost of the call. Scraper endpoints need a key with the `scrape` scope.

**One call, structured data**

```bash
curl "https://hproxy.com/api/v1/scrape/threads/search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

> [!WARNING] **Scrapers change often**: A scraper reads a website we do not control. When that website changes its pages, its limits or how it blocks automated traffic, a scraper can fail, return fewer fields, or return fields in a different shape until we update it, and we update scrapers often. **Scrapers are not a stable product that never breaks.** Handle errors and retry, read the fields inside `data` defensively, subscribe to [service notices](https://hproxy.com/docs/announcements), and do not promise your customers that a scraper will never change or never fail. The envelope around `data` keeps its shape.

### You bring a key. We handle everything else.

A scraper call needs **no proxies, no headless browsers, no captcha solving and no parsers** on your side. We route every request through our own proxy network, deal with captchas and block pages, and parse the result into stable, structured JSON. All of that is included in the per-call price: there is nothing to set up, rotate, warm up or maintain. And if a call fails anyway, it is never billed: errors, timeouts and rate limits cost nothing.

### Every platform

All 23 platforms, 116 endpoints, every one callable the same way. Each tile opens that platform's full API reference: every endpoint with its cost, path, parameters and a copy-paste example. Or browse the [complete catalog](https://hproxy.com/docs/scrapers/catalog).

- Instagram (`instagram`): 11 endpoints
- TikTok (`tiktok`): 23 endpoints
- YouTube (`youtube`): 13 endpoints
- Twitter / X (`twitter`): 6 endpoints
- LinkedIn (`linkedin`): 6 endpoints
- Google (`google`): 4 endpoints
- Facebook (`facebook`): 17 endpoints
- Reddit (`reddit`): 5 endpoints
- Threads (`threads`): 5 endpoints
- Bluesky (`bluesky`): 3 endpoints
- Truth Social (`truth-social`): 3 endpoints
- Pinterest (`pinterest`): 4 endpoints
- Twitch (`twitch`): 4 endpoints
- Snapchat (`snapchat`): 1 endpoint
- Spotify (`spotify`): 3 endpoints
- SoundCloud (`soundcloud`): 1 endpoint
- Kick (`kick`): 1 endpoint
- Linktree (`linktree`): 1 endpoint
- Komi (`komi`): 1 endpoint
- Pillar (`pillar`): 1 endpoint
- Lnk.Bio (`linkbio`): 1 endpoint
- Linkme (`linkme`): 1 endpoint
- Amazon (`amazon`): 1 endpoint

### Billing, exact and per success

Billing is **per successful call** at the exact price listed for each scraper: every standard endpoint costs **$0.00149 per call** ($1.49 per 1,000 calls). There is **no per-call minimum**: sub-cent prices are billed exactly. Your wallet accrues the fractional cost and debits whole cents only as they add up, so 1,000 calls at $0.00149 debit exactly $1.49, never more.

A successful call counts even when the search finds nothing, and so does a lookup whose target does not exist: the platform was queried either way. Errors, timeouts and rate-limited calls are never charged. Pricing is per call, not per result: one call returning 50 items is still one call.

- [Run a scraper](https://hproxy.com/docs/scrapers/run): The request shape, inputs and idempotency.
- [The response envelope](https://hproxy.com/docs/scrapers/envelope): The stable shape every call returns.
- [Call history & billing audit](https://hproxy.com/docs/scrapers/runs): Reconcile your bill to the cent.
- [The catalog](https://hproxy.com/docs/scrapers/catalog): All 116 endpoints across 23 platforms.

## Run a scraper

*GET or POST /api/v1/scrape/{platform}/{action}: inputs as query parameters or a JSON body, X-Request-Id idempotency, and the exact per-call price.*

URL: https://hproxy.com/docs/scrapers/run

#### GET /api/v1/scrape/{platform}/{action}

**Run a scraper.** Call a specific platform action (e.g. `threads/search` or `tiktok/profile`). Pass inputs as query parameters, or `POST` the same fields as a JSON body. Each scraper's exact inputs are in the [catalog](https://hproxy.com/docs/scrapers/catalog): profile actions take `handle`, page actions take `url`, search actions take `query` and, where supported, a `start_date` / `end_date` window. Boolean and integer inputs work in query strings too (`trim=true` is fine). Send an optional `X-Request-Id` header with a unique value and a retry of the same request replays the original result instead of running (and billing) again.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `handle` | `string (query)` | optional | Handle/username, for profile-style actions. |
| `url` | `string (query)` | optional | Target URL, when the action scrapes a specific page. |
| `query` | `string (query)` | optional | Search term, for search actions. |
| `start_date` | `string (query)` | optional | YYYY-MM-DD. Search actions that support it return posts from this date onward. |
| `end_date` | `string (query)` | optional | YYYY-MM-DD. Upper bound of the search window. |
| `X-Request-Id` | `string (header)` | optional | Idempotency: a retry with the same value returns the original run's result and is never billed twice. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/threads/search?query=coffee&start_date=2026-07-01&end_date=2026-07-22" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "threads",
  "scraper": "threads-search-by-keyword",
  "input": { "query": "coffee", "start_date": "2026-07-01", "end_date": "2026-07-22" },
  "data": {
    "posts": [
      {
        "id": "3946970838407495095_66444372064",
        "code": "DbGdRDKGr23",
        "caption": { "text": "Take your time this morning. Drink your coffee…" },
        "like_count": 24,
        "taken_at": 1784735611,
        "url": "https://www.threads.com/@comeupkelci/post/DbGdRDKGr23",
        "user": { "username": "comeupkelci", "full_name": "Kelci", "is_verified": false, "profile_pic_url": "…" }
      }
    ]
  },
  "records": 19,
  "costUsd": 0.003,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 5211
}
```

> [!NOTE] **No proxies, no captchas, no infrastructure.** The call price includes our proxy network, captcha handling and parsing. You only ever send the request above.

The full list of every platform and action is in the [Scraper catalog](https://hproxy.com/docs/scrapers/catalog), or fetch it as JSON from `GET https://hproxy.com/api/v1/scrapers` (no key required).

## Caching: free cached reads

*Pass cache_max_age and accept a result up to 30 days old. Cached responses return in about a second and cost nothing. You are only billed for live scrapes.*

URL: https://hproxy.com/docs/scrapers/caching

Plenty of scraping does not need a result from this second. A profile you enriched last Tuesday, a post whose engagement you are trending weekly, a catalog you re-check monthly: for all of it, a recent answer is as good as a live one and a lot faster to get.

Add **`cache_max_age`** to any supported call and we will serve a stored result if one that fresh exists. It comes back in about a second instead of a live scrape, and **it is free**: a cached read is not billed at all.

> [!TIP] **The pricing, plainly**: Cached reads cost **$0.00**. You are only charged when we actually go and scrape. So `cache_max_age` is never worse than omitting it: at best you pay nothing and get an instant answer, at worst you pay the normal price for a live result.

### How to use it

*Parameter*

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `cache_max_age` | `1d | 3d | 7d | 14d | 30d` | optional | The oldest result you are willing to accept. Anything outside this set returns a `400`. Omit the parameter entirely for a guaranteed-live scrape. |

**cURL**

```bash
# Happy with a result up to a week old, and pay nothing if we have one
curl "https://hproxy.com/api/v1/scrape/tiktok/profile?handle=levelsio&cache_max_age=7d" \
  -H "X-API-Key: hpx_your_key_here"
```

**Python**

```python
import requests

r = requests.get(
    "https://hproxy.com/api/v1/scrape/tiktok/profile",
    params={"handle": "levelsio", "cache_max_age": "7d"},
    headers={"X-API-Key": "hpx_your_key_here"},
).json()

if r.get("cached"):
    print("free, served from cache at", r["cached_at"])
```

### Reading the response

A cached response carries two extra fields so you always know what you got and what it cost. A live response carries neither.

*Field*

| Field | Type | Description |
| --- | --- | --- |
| `cached` | `boolean` | `true` when the result came from cache. Absent on a live scrape. |
| `cached_at` | `timestamp` | When the cached copy was originally scraped, so you can judge the age yourself. |
| `walletDebitUsd` | `number` | `0` on a cached read. This is the field to reconcile against, on any call. |

### What it does and does not do

`cache_max_age` is an **acceptance threshold**, not a cache selector. Every value reads the same stored copy; you are only saying how old a copy you will take. So asking for `1d` and asking for `30d` can return the identical response, and asking for `1d` when the stored copy is a week old triggers a fresh live scrape (and a normal charge) which then refreshes the cache for everyone.

It is available on the endpoints where a cached answer is meaningful: profiles, posts, transcripts, channels, ad details and link-in-bio pages. Search, trending and comment feeds are always live, because a stale answer there is not an answer. The [Scraper catalog](https://hproxy.com/docs/scrapers/catalog) lists `cache_max_age` in the inputs of every endpoint that accepts it.

## The response envelope

*Every scraper call returns the same stable envelope: data plus bookkeeping, with costUsd (exact price) and walletDebitUsd (whole cents actually settled).*

URL: https://hproxy.com/docs/scrapers/envelope

#### GET /api/v1/scrape/{platform}/{action}

**The envelope, field by field.** Every scraper call returns the same stable envelope. `data` is the platform's structured payload; everything else is bookkeeping. `costUsd` is the call's exact price (for a $0.00149 scraper it reads `0.00149`, there is no minimum). `walletDebitUsd` is what actually left your wallet on **this** call: fractional costs accrue on a running tab and settle in whole cents, so it reads `0` on most calls and `0.01` as the tab crosses each cent. Summing either field over many calls converges on the same total.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform segment you called, e.g. "threads". |
| `scraper` | `string` | Internal scraper id the path resolved to. |
| `input` | `object` | Echo of the inputs the run used. |
| `data` | `object` | The scraped payload, exactly as structured by the platform. |
| `records` | `integer` | Result count heuristic (longest array in data). Informational only: billing is per call, never per record. |
| `costUsd` | `number` | The call's exact price in USD. 0 on an idempotent replay. |
| `walletDebitUsd` | `number` | Whole cents actually settled from the wallet on this call. |
| `idempotentReplay` | `boolean` | Present and true when X-Request-Id matched a previous run and its result was replayed free. |
| `requestId` | `string` | The run id. Quote it in support tickets. |
| `elapsedMs` | `integer` | Server-side duration of the call. |

**Envelope**

```json
{
  "platform": "threads",
  "scraper": "threads-search-by-keyword",
  "input": { "query": "coffee" },
  "data": { "posts": [ … ] },
  "records": 19,
  "costUsd": 0.003,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 5211
}
```

**Error response**

```json
{
  "error": "Invalid input.",
  "details": "'trim' must be a boolean",
  "requestId": null
}
```

Errors skip the envelope and return the engine's status with a JSON body: `400` invalid input, `402` balance or spend cap, `429` rate limited with `Retry-After`, `502` upstream failure (never billed).

## Your call history

*GET /api/v1/scrape/runs audits every scraper call: exact per-call cost, what settled from the wallet, rolling 24h totals and the pending sub-cent tab.*

URL: https://hproxy.com/docs/scrapers/runs

#### GET /api/v1/scrape/runs

**Your call history.** Audit every scraper call your account made: exact per-call cost, what settled from the wallet, status and result count, plus rolling 24h totals and the pending sub-cent tab. Use it to reconcile your bill to the cent. Optional `limit` query parameter (default 50, max 200). Also visible in your [dashboard](https://hproxy.com/dashboard/scrapers).

**Request**

```bash
curl "https://hproxy.com/api/v1/scrape/runs?limit=2" -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "count": 2,
  "runs": [
    {
      "id": "c4389b749c07d44209e4fb301",
      "scraper": "threads-search-by-keyword",
      "endpoint": "/api/v1/scrape/threads/search",
      "status": "SUCCESS",
      "records": 19,
      "costUsd": 0.003,
      "walletDebitUsd": 0,
      "elapsedMs": 5211,
      "requestId": null,
      "createdAt": "2026-07-22T15:41:09.114Z"
    }
  ],
  "summary": {
    "last24h": { "calls": 2, "costUsd": 0.006, "walletDebitedUsd": 0 },
    "pendingTabUsd": 0.006
  }
}
```

## Scraper catalog

*Every scraper endpoint: 116 actions across 23 platforms with per-call price and exact inputs. Searchable, and available as JSON at GET /api/v1/scrapers.*

URL: https://hproxy.com/docs/scrapers/catalog

All 116 scrapers across 23 platforms, each callable as `GET https://hproxy.com/api/v1/scrape/{platform}/{action}` with a `scrape` key. Fetch the same list as JSON from `GET https://hproxy.com/api/v1/scrapers` (no key required). Every platform also has a full landing page with examples under [/scrapers](https://hproxy.com/scrapers).

### Every scraper (116 total)
Call any as: GET https://hproxy.com/api/v1/scrape/{platform}/{action}?<input>=<value> (or POST with a JSON body). Needs the `scrape` scope. Billed per successful call at the listed price (exact fractional billing, no per-call minimum). Format: action, name, price/call, inputs (? = optional, (a|b) = the ONLY accepted values).

#### instagram
- profile, Instagram Profile, $0.00149/call, handle:string, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- post, Instagram Post, $0.0149/call, url:url, region?:string, trim?:boolean, download_media?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- transcript, Instagram Media Transcript, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- reels-search, Instagram Reels Search, $0.00149/call, query:string, date_posted?:string(last-hour|last-day|last-week|last-month|last-year), page?:integer
- basic-profile, Instagram Basic Profile, $0.00149/call, userId:string, cache_max_age?:string(1d|3d|7d|14d|30d)
- posts, Instagram User Posts, $0.00149/call, handle:string, next_max_id?:string, trim?:boolean
- reels, Instagram User Reels, $0.00149/call, user_id?:string, handle?:string, max_id?:string, trim?:boolean
- comments, Instagram Post Comments, $0.00149/call, url:url, cursor?:string, trim?:boolean
- highlights, Instagram User Highlights, $0.00149/call, user_id?:string, handle?:string
- highlight, Instagram Highlight Detail, $0.00149/call, id:string
- embed, Instagram Profile Embed HTML, $0.00149/call, handle:string, trim?:boolean

#### tiktok
- profile, TikTok Profile, $0.00149/call, handle?:string, user_id?:string, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- profile-region, TikTok Profile Region, $0.00149/call, handle:string, trim?:boolean
- audience, TikTok User Audience Demographics, $0.03874/call, handle:string, trim?:boolean
- video, TikTok Video, $0.0149/call, url:url, get_transcript?:boolean, region?:string, trim?:boolean, download_media?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- video-transcript, TikTok Video Transcript, $0.01639/call, url:url, language?:string, use_ai_as_fallback?:string
- profile-videos, TikTok Profile Videos, $0.00149/call, handle:string, user_id?:string, max_cursor?:string, sort_by?:string(latest|popular), region?:string, trim?:boolean
- search, TikTok Keyword Search, $0.00149/call, query:string, date_posted?:string(yesterday|this-week|this-month|last-3-months|last-6-months|all-time), sort_by?:string(relevance|most-liked|date-posted), region?:string, cursor?:integer, trim?:boolean
- shop-search, TikTok Shop Search, $0.00149/call, query:string, page?:integer, region?:string
- live-status, TikTok Live Status, $0.00149/call, handle:string, trim?:boolean
- video-comments, TikTok Video Comments, $0.00149/call, url:url, cursor?:integer, trim?:boolean
- comment-replies, TikTok Comment Replies, $0.00149/call, comment_id:string, url:url, cursor?:integer
- following, TikTok User Following, $0.00149/call, handle:string, min_time?:integer, trim?:boolean
- followers, TikTok User Followers, $0.00149/call, handle?:string, user_id?:string, min_time?:integer, trim?:boolean
- search-users, TikTok Search Users, $0.00149/call, query:string, cursor?:string, trim?:boolean
- search-hashtag, TikTok Hashtag Search, $0.00149/call, hashtag:string, region?:string, cursor?:integer, trim?:boolean
- song, TikTok Song Details, $0.00149/call, clipId:string, cursor?:integer
- song-videos, TikTok Song Videos, $0.00149/call, clipId:string, cursor?:integer
- trending, TikTok Trending Feed, $0.00149/call, region:string, trim?:boolean
- shop-products, TikTok Shop Products, $0.00149/call, url:url, cursor?:string, region?:string, sort_by?:string(top|new_releases)
- shop-product, TikTok Shop Product Details, $0.00149/call, url:url, region?:string
- shop-product-reviews, TikTok Shop Product Reviews, $0.00149/call, url?:url, product_id?:string, region?:string, page?:integer
- search-top, TikTok Top Search, $0.00149/call, query:string, publish_time?:string(yesterday|this-week|this-month|last-3-months|last-6-months|all-time), sort_by?:string(relevance|most-liked|date-posted), region?:string, cursor?:integer
- shop-showcase, TikTok Shop User Showcase, $0.00149/call, handle:string, region?:string, cursor?:string

#### youtube
- channel-lookup, YouTube Channel, $0.00149/call, channelId?:string, handle?:string, url?:url, cache_max_age?:string(1d|3d|7d|14d|30d)
- channel, YouTube Channel, $0.00149/call, channelId?:string, handle?:string, url?:url, cache_max_age?:string(1d|3d|7d|14d|30d)
- channel-videos, YouTube Channel Videos, $0.00149/call, channelId?:string, handle?:string, sort?:string(latest|popular), continuationToken?:string, includeExtras?:boolean, is_paid_promotions?:boolean
- channel-shorts, YouTube Channel Shorts, $0.00149/call, channelId?:string, handle?:string, sort?:string(newest|popular), continuationToken?:string, includeExtras?:boolean
- video, YouTube Video, $0.00149/call, url:url, language?:string, cache_max_age?:string(1d|3d|7d|14d|30d)
- transcript, YouTube Video Transcript, $0.00149/call, url:url, language?:string, cache_max_age?:string(1d|3d|7d|14d|30d)
- search, YouTube Search, $0.00149/call, query:string, uploadDate?:string(today|this_week|this_month|this_year), sortBy?:string(relevance|popular), type?:string(videos|shorts|channels|playlists), duration?:string(under_3_min|between_3_and_20_min|over_20_min), region?:string, continuationToken?:string, includeExtras?:boolean
- comments, YouTube Video Comments, $0.00149/call, url:url, continuationToken?:string, order?:string(top|newest)
- trending-shorts, YouTube Trending Shorts, $0.00149/call, no inputs
- search-hashtag, YouTube Hashtag Search, $0.00149/call, hashtag:string, continuationToken?:string, type?:string(all|shorts)
- comment-replies, YouTube Comment Replies, $0.00149/call, continuationToken:string
- playlist, YouTube Playlist, $0.00149/call, playlist_id:string
- community-post, YouTube Community Post, $0.00149/call, url:url, trim?:boolean

#### twitter
- tweets, Twitter User Tweets, $0.00149/call, handle:string, trim?:boolean
- profile, Twitter / X Profile, $0.00149/call, handle:string, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- tweet, Twitter / X Tweet, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- tweet-transcript, Twitter / X Tweet Transcript, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- community, Twitter / X Community, $0.00149/call, url:url, trim?:boolean
- community-tweets, Twitter / X Community Tweets, $0.00149/call, url:url, trim?:boolean

#### linkedin
- profile, LinkedIn Profile, $0.00149/call, url:url, trim?:boolean
- company, LinkedIn Company, $0.00149/call, url:url, trim?:boolean
- company-posts, LinkedIn Company Posts, $0.00149/call, url:url, page?:integer
- post, LinkedIn Post, $0.00149/call, url:url, trim?:boolean
- ad-search, LinkedIn Ad Library Search, $0.00149/call, company?:string, keyword?:string, companyId?:string, countries?:string, startDate?:string, endDate?:string, paginationToken?:string
- ad, LinkedIn Ad Detail, $0.00149/call, url:url, trim?:boolean

#### google
- search, Google Search Results, $0.00149/call, query:string, region?:string, date_posted?:string(last-hour|last-day|last-week|last-month|last-year), page?:integer
- ad-company, Google Ad Library Company Ads, $0.03725/call, domain?:string, advertiser_id?:string, topic?:string(all|political), region?:string, start_date?:string, end_date?:string, platform?:string(google_maps|google_play|google_search|google_shopping|youtube), format?:string(text|image|video), get_ad_details?:boolean, cursor?:string
- ad, Google Ad Detail, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- advertiser-search, Google Advertiser Search, $0.00149/call, query:string, cursor?:string, region?:string, trim?:boolean

#### facebook
- profile, Facebook Profile, $0.00149/call, url:url, get_business_hours?:boolean, include_gated_profile?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- profile-reels, Facebook Profile Reels, $0.00149/call, url:url, next_page_id?:string, cursor?:string
- profile-photos, Facebook Profile Photos, $0.00149/call, url:url, next_page_id?:string, cursor?:string
- profile-posts, Facebook Profile Posts, $0.00149/call, url?:url, pageId?:string, cursor?:string
- profile-events, Facebook Profile Events, $0.00149/call, url:url, cursor?:string
- post, Facebook Post, $0.00149/call, url:url, get_comments?:boolean, get_transcript?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- post-transcript, Facebook Post Transcript, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- post-comments, Facebook Post Comments, $0.00149/call, url?:url, feedback_id?:string, cursor?:string
- comment-replies, Facebook Comment Replies, $0.00149/call, feedback_id:string, expansion_token:string, cursor?:string
- group-posts, Facebook Group Posts, $0.00149/call, url?:url, group_id?:string, sort_by?:string(TOP_POSTS|RECENT_ACTIVITY|CHRONOLOGICAL|CHRONOLOGICAL_LISTINGS), cursor?:string
- events-search, Facebook Events Search, $0.00149/call, query:string, cursor?:string
- events, Facebook Events by City, $0.00149/call, url:url, time?:string(today|this_week|next_week), cursor?:string
- event, Facebook Event Details, $0.00149/call, id?:string, url?:url
- ad, Facebook Ad Library Detail, $0.00149/call, id?:string, url?:url, get_transcript?:boolean, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- ad-search, Facebook Ad Library Search, $0.00149/call, query:string, sort_by?:string(total_impressions|relevancy_monthly_grouped), search_type?:string(keyword_unordered|keyword_exact_phrase), ad_type?:string(all|political_and_issue_ads), country?:string, status?:string(ALL|ACTIVE|INACTIVE), media_type?:string(ALL|IMAGE|VIDEO|MEME|IMAGE_AND_MEME|NONE), start_date?:string, end_date?:string, cursor?:string, trim?:boolean
- ad-company, Facebook Company Ads, $0.00149/call, pageId?:string, companyName?:string, country?:string, status?:string(ALL|ACTIVE|INACTIVE), language?:string, cursor?:string, media_type?:string(ALL|IMAGE|VIDEO|MEME|IMAGE_AND_MEME|NONE), sort_by?:string(total_impressions|relevancy_monthly_grouped), start_date?:string, end_date?:string, trim?:boolean
- ad-companies-search, Facebook Ad Library Company Search, $0.00149/call, query:string, cursor?:string, trim?:boolean

#### reddit
- subreddit, Reddit Subreddit Details, $0.00149/call, subreddit?:string, url?:url, cache_max_age?:string(1d|3d|7d|14d|30d)
- subreddit-posts, Reddit Subreddit Posts, $0.00149/call, subreddit:string, timeframe?:string(all|day|week|month|year), sort?:string(best|hot|new|top|rising), after?:string, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- comments, Reddit Post Comments, $0.00149/call, url:url, cursor?:string, trim?:boolean
- search, Reddit Search, $0.00149/call, query:string, sort?:string(relevance|new|top|comment_count), timeframe?:string(all|day|week|month|year), after?:string, trim?:boolean
- subreddit-search, Reddit Subreddit Search, $0.00149/call, subreddit:string, query?:string, sort?:string(relevance|hot|top|new|comments), timeframe?:string(all|year|month|week|day|hour), cursor?:string

#### threads
- profile, Threads Profile, $0.00149/call, handle:string, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- posts, Threads User Posts, $0.00149/call, handle:string, user_id?:string, trim?:boolean
- post, Threads Post, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- search, Threads Search, $0.00149/call, query:string, start_date?:string, end_date?:string, trim?:boolean
- search-users, Threads Search Users, $0.00149/call, query:string

#### bluesky
- profile, Bluesky Profile, $0.00149/call, handle:string, trim?:boolean
- posts, Bluesky User Posts, $0.00149/call, handle?:string, user_id?:string
- post, Bluesky Post, $0.00149/call, url:url, trim?:boolean

#### truth-social
- profile, Truth Social Profile, $0.00149/call, handle:string, trim?:boolean
- posts, Truth Social User Posts, $0.00149/call, handle?:string, user_id?:string, next_max_id?:string, trim?:boolean
- post, Truth Social Post, $0.00149/call, url:url, trim?:boolean

#### pinterest
- search, Pinterest Search, $0.00149/call, query:string, cursor?:string, trim?:boolean
- pin, Pinterest Pin, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- boards, Pinterest User Boards, $0.00149/call, handle:string, trim?:boolean
- board, Pinterest Board Pins, $0.00149/call, url:url, cursor?:string, trim?:boolean

#### twitch
- profile, Twitch Profile, $0.00149/call, handle:string, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- videos, Twitch User Videos, $0.00149/call, handle:string, filter_by?:string(HIGHLIGHT|ARCHIVE|UPLOAD), sort_by?:string(TIME|VIEWS)
- clip, Twitch Clip, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)
- schedule, Twitch User Schedule, $0.00149/call, handle:string, trim?:boolean

#### snapchat
- profile, Snapchat Profile, $0.00149/call, handle:string, trim?:boolean

#### spotify
- artist, Spotify Artist, $0.00149/call, id?:string, url?:url
- track, Spotify Track, $0.00149/call, id?:string, url?:url
- album, Spotify Album, $0.00149/call, id?:string, url?:url

#### soundcloud
- artist, SoundCloud Artist, $0.00149/call, handle?:string, url?:url

#### kick
- clip, Kick Clip, $0.00149/call, url:url, trim?:boolean

#### linktree
- page, Linktree Page, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)

#### komi
- page, Komi Page, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)

#### pillar
- page, Pillar Page, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)

#### linkbio
- page, Linkbio Page, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)

#### linkme
- page, Linkme Profile, $0.00149/call, url:url, trim?:boolean, cache_max_age?:string(1d|3d|7d|14d|30d)

#### amazon
- shop, Amazon Shop Page, $0.00149/call, url:url, trim?:boolean

## Instagram scraper API

*Every Instagram scraper endpoint: 11 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/instagram

All 11 Instagram endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/instagram/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Instagram landing page](https://hproxy.com/scrapers/instagram) for examples and use cases.

#### GET /api/v1/scrape/instagram/profile

**Instagram Profile.** Returns structured JSON for **Instagram Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/profile?handle=instagram" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-profile",
  "input": { "handle": "instagram" },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/post

**Instagram Post.** Returns structured JSON for **Instagram Post**. Billed **$0.0149 per successful call** ($14.90 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `download_media` | `boolean (query)` | optional | Return a direct media URL alongside the metadata. |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/post?url=https://www.instagram.com/p/C8Xxun_Ku3-/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-post",
  "input": { "url": "https://www.instagram.com/p/C8Xxun_Ku3-/" },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.0149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/transcript

**Instagram Media Transcript.** Returns structured JSON for **Instagram Media Transcript**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/transcript?url=https://www.instagram.com/p/C8Xxun_Ku3-/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-transcript",
  "input": { "url": "https://www.instagram.com/p/C8Xxun_Ku3-/" },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/reels-search

**Instagram Reels Search.** Returns structured JSON for **Instagram Reels Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `date_posted` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. Allowed values: `last-hour`, `last-day`, `last-week`, `last-month`, `last-year`. |
| `page` | `integer (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/reels-search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-reels-search",
  "input": { "query": "coffee" },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/basic-profile

**Instagram Basic Profile.** Returns structured JSON for **Instagram Basic Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `userId` | `string (query)` | required | Identifier from a previous response. |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/basic-profile?userId=1234567890" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-basic-profile",
  "input": { "userId": "1234567890" },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/posts

**Instagram User Posts.** Returns structured JSON for **Instagram User Posts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `next_max_id` | `string (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/posts?handle=instagram" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-posts",
  "input": { "handle": "instagram" },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/reels

**Instagram User Reels.** Returns structured JSON for **Instagram User Reels**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `user_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle`. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `user_id`. |
| `max_id` | `string (query)` | optional | Identifier from a previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/reels?handle=instagram" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-reels",
  "input": {  },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/comments

**Instagram Post Comments.** Returns structured JSON for **Instagram Post Comments**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/comments?url=https://www.instagram.com/p/C8Xxun_Ku3-/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-comments",
  "input": { "url": "https://www.instagram.com/p/C8Xxun_Ku3-/" },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/highlights

**Instagram User Highlights.** Returns structured JSON for **Instagram User Highlights**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `user_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle`. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `user_id`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/highlights?handle=instagram" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-highlights",
  "input": {  },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/highlight

**Instagram Highlight Detail.** Returns structured JSON for **Instagram Highlight Detail**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `id` | `string (query)` | required | Identifier from a previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/highlight?id=1234567890" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-highlight",
  "input": { "id": "1234567890" },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/instagram/embed

**Instagram Profile Embed HTML.** Returns structured JSON for **Instagram Profile Embed HTML**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/instagram/embed?handle=instagram" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "instagram",
  "scraper": "instagram-embed",
  "input": { "handle": "instagram" },
  "data": { /* the Instagram payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## TikTok scraper API

*Every TikTok scraper endpoint: 23 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/tiktok

All 23 TikTok endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/tiktok/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [TikTok landing page](https://hproxy.com/scrapers/tiktok) for examples and use cases.

#### GET /api/v1/scrape/tiktok/profile

**TikTok Profile.** Returns structured JSON for **TikTok Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `user_id`. |
| `user_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle`. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/profile?handle=tiktok" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-profile",
  "input": {  },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/profile-region

**TikTok Profile Region.** Returns structured JSON for **TikTok Profile Region**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/profile-region?handle=tiktok" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-profile-region",
  "input": { "handle": "tiktok" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/audience

**TikTok User Audience Demographics.** Returns structured JSON for **TikTok User Audience Demographics**. Billed **$0.03874 per successful call** ($38.74 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/audience?handle=tiktok" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-audience",
  "input": { "handle": "tiktok" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.03874,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/video

**TikTok Video.** Returns structured JSON for **TikTok Video**. Billed **$0.0149 per successful call** ($14.90 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `get_transcript` | `boolean (query)` | optional | Also include transcript in the response. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `download_media` | `boolean (query)` | optional | Return a direct media URL alongside the metadata. |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/video?url=https://www.tiktok.com/@tiktok/video/7106594312292453675" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-video",
  "input": { "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.0149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/video-transcript

**TikTok Video Transcript.** Returns structured JSON for **TikTok Video Transcript**. Billed **$0.01639 per successful call** ($16.39 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `language` | `string (query)` | optional | Two-letter language code, e.g. en. |
| `use_ai_as_fallback` | `string (query)` | optional | The use ai as fallback parameter. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/video-transcript?url=https://www.tiktok.com/@tiktok/video/7106594312292453675" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-video-transcript",
  "input": { "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.01639,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/profile-videos

**TikTok Profile Videos.** Returns structured JSON for **TikTok Profile Videos**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `user_id` | `string (query)` | optional | Identifier from a previous response. |
| `max_cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `sort_by` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `latest`, `popular`. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/profile-videos?handle=tiktok" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-profile-videos",
  "input": { "handle": "tiktok" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/search

**TikTok Keyword Search.** Returns structured JSON for **TikTok Keyword Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `date_posted` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. Allowed values: `yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`, `all-time`. |
| `sort_by` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `relevance`, `most-liked`, `date-posted`. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `cursor` | `integer (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-search",
  "input": { "query": "coffee" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/shop-search

**TikTok Shop Search.** Returns structured JSON for **TikTok Shop Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `page` | `integer (query)` | optional | Pagination token from the previous response. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/shop-search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-shop-search",
  "input": { "query": "coffee" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/live-status

**TikTok Live Status.** Returns structured JSON for **TikTok Live Status**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/live-status?handle=tiktok" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-live-status",
  "input": { "handle": "tiktok" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/video-comments

**TikTok Video Comments.** Returns structured JSON for **TikTok Video Comments**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `cursor` | `integer (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/video-comments?url=https://www.tiktok.com/@tiktok/video/7106594312292453675" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-video-comments",
  "input": { "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/comment-replies

**TikTok Comment Replies.** Returns structured JSON for **TikTok Comment Replies**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `comment_id` | `string (query)` | required | Identifier from a previous response. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `cursor` | `integer (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/comment-replies?comment_id=1234567890&url=https://www.tiktok.com/@tiktok/video/7106594312292453675" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-comment-replies",
  "input": { "comment_id": "1234567890", "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/following

**TikTok User Following.** Returns structured JSON for **TikTok User Following**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `min_time` | `integer (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/following?handle=tiktok" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-following",
  "input": { "handle": "tiktok" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/followers

**TikTok User Followers.** Returns structured JSON for **TikTok User Followers**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `user_id`. |
| `user_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle`. |
| `min_time` | `integer (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/followers?handle=tiktok" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-followers",
  "input": {  },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/search-users

**TikTok Search Users.** Returns structured JSON for **TikTok Search Users**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/search-users?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-search-users",
  "input": { "query": "coffee" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/search-hashtag

**TikTok Hashtag Search.** Returns structured JSON for **TikTok Hashtag Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `hashtag` | `string (query)` | required | Hashtag to look up, without the # sign. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `cursor` | `integer (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/search-hashtag?hashtag=travel" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-search-hashtag",
  "input": { "hashtag": "travel" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/song

**TikTok Song Details.** Returns structured JSON for **TikTok Song Details**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `clipId` | `string (query)` | required | Identifier from a previous response. |
| `cursor` | `integer (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/song?clipId=1234567890" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-song",
  "input": { "clipId": "1234567890" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/song-videos

**TikTok Song Videos.** Returns structured JSON for **TikTok Song Videos**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `clipId` | `string (query)` | required | Identifier from a previous response. |
| `cursor` | `integer (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/song-videos?clipId=1234567890" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-song-videos",
  "input": { "clipId": "1234567890" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/trending

**TikTok Trending Feed.** Returns structured JSON for **TikTok Trending Feed**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `region` | `string (query)` | required | Two-letter region/country code, e.g. US. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/trending?region=US" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-trending",
  "input": { "region": "US" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/shop-products

**TikTok Shop Products.** Returns structured JSON for **TikTok Shop Products**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `sort_by` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `top`, `new_releases`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/shop-products?url=https://www.tiktok.com/@tiktok/video/7106594312292453675" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-shop-products",
  "input": { "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/shop-product

**TikTok Shop Product Details.** Returns structured JSON for **TikTok Shop Product Details**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/shop-product?url=https://www.tiktok.com/@tiktok/video/7106594312292453675" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-shop-product",
  "input": { "url": "https://www.tiktok.com/@tiktok/video/7106594312292453675" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/shop-product-reviews

**TikTok Shop Product Reviews.** Returns structured JSON for **TikTok Shop Product Reviews**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `product_id`. |
| `product_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `url`. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `page` | `integer (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/shop-product-reviews?url=https://www.tiktok.com/@tiktok/video/7106594312292453675" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-shop-product-reviews",
  "input": {  },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/search-top

**TikTok Top Search.** Returns structured JSON for **TikTok Top Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `publish_time` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. Allowed values: `yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`, `all-time`. |
| `sort_by` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `relevance`, `most-liked`, `date-posted`. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `cursor` | `integer (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/search-top?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-search-top",
  "input": { "query": "coffee" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/tiktok/shop-showcase

**TikTok Shop User Showcase.** Returns structured JSON for **TikTok Shop User Showcase**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/tiktok/shop-showcase?handle=tiktok" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "tiktok",
  "scraper": "tiktok-shop-showcase",
  "input": { "handle": "tiktok" },
  "data": { /* the TikTok payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## YouTube scraper API

*Every YouTube scraper endpoint: 13 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/youtube

All 13 YouTube endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/youtube/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [YouTube landing page](https://hproxy.com/scrapers/youtube) for examples and use cases.

#### GET /api/v1/scrape/youtube/channel-lookup

**YouTube Channel.** Returns structured JSON for **YouTube Channel**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `channelId` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle` or `url`. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `channelId` or `url`. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `channelId` or `handle`. |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/channel-lookup?handle=MrBeast" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-channel-lookup",
  "input": {  },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/channel

**YouTube Channel.** Returns structured JSON for **YouTube Channel**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `channelId` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle` or `url`. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `channelId` or `url`. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `channelId` or `handle`. |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/channel?handle=MrBeast" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-channel",
  "input": {  },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/channel-videos

**YouTube Channel Videos.** Returns structured JSON for **YouTube Channel Videos**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `channelId` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle`. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `channelId`. |
| `sort` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `latest`, `popular`. |
| `continuationToken` | `string (query)` | optional | Pagination token from the previous response. |
| `includeExtras` | `boolean (query)` | optional | Optional flag (true or false). |
| `is_paid_promotions` | `boolean (query)` | optional | Optional flag (true or false). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/channel-videos?handle=MrBeast" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-channel-videos",
  "input": {  },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/channel-shorts

**YouTube Channel Shorts.** Returns structured JSON for **YouTube Channel Shorts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `channelId` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle`. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `channelId`. |
| `sort` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `newest`, `popular`. |
| `continuationToken` | `string (query)` | optional | Pagination token from the previous response. |
| `includeExtras` | `boolean (query)` | optional | Optional flag (true or false). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/channel-shorts?handle=MrBeast" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-channel-shorts",
  "input": {  },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/video

**YouTube Video.** Returns structured JSON for **YouTube Video**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `language` | `string (query)` | optional | Two-letter language code, e.g. en. |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/video?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-video",
  "input": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/transcript

**YouTube Video Transcript.** Returns structured JSON for **YouTube Video Transcript**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `language` | `string (query)` | optional | Two-letter language code, e.g. en. |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/transcript?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-transcript",
  "input": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/search

**YouTube Search.** Returns structured JSON for **YouTube Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `uploadDate` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. Allowed values: `today`, `this_week`, `this_month`, `this_year`. |
| `sortBy` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `relevance`, `popular`. |
| `type` | `string (query)` | optional | The type parameter. Allowed values: `videos`, `shorts`, `channels`, `playlists`. |
| `duration` | `string (query)` | optional | The duration parameter. Allowed values: `under_3_min`, `between_3_and_20_min`, `over_20_min`. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `continuationToken` | `string (query)` | optional | Pagination token from the previous response. |
| `includeExtras` | `boolean (query)` | optional | Optional flag (true or false). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-search",
  "input": { "query": "coffee" },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/comments

**YouTube Video Comments.** Returns structured JSON for **YouTube Video Comments**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `continuationToken` | `string (query)` | optional | Pagination token from the previous response. |
| `order` | `string (query)` | optional | The order parameter. Allowed values: `top`, `newest`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/comments?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-comments",
  "input": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/trending-shorts

**YouTube Trending Shorts.** Returns structured JSON for **YouTube Trending Shorts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/trending-shorts" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-trending-shorts",
  "input": {  },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/search-hashtag

**YouTube Hashtag Search.** Returns structured JSON for **YouTube Hashtag Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `hashtag` | `string (query)` | required | Hashtag to look up, without the # sign. |
| `continuationToken` | `string (query)` | optional | Pagination token from the previous response. |
| `type` | `string (query)` | optional | The type parameter. Allowed values: `all`, `shorts`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/search-hashtag?hashtag=travel" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-search-hashtag",
  "input": { "hashtag": "travel" },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/comment-replies

**YouTube Comment Replies.** Returns structured JSON for **YouTube Comment Replies**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `continuationToken` | `string (query)` | required | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/comment-replies?continuationToken=value" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-comment-replies",
  "input": { "continuationToken": "value" },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/playlist

**YouTube Playlist.** Returns structured JSON for **YouTube Playlist**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `playlist_id` | `string (query)` | required | Identifier from a previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/playlist?playlist_id=1234567890" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-playlist",
  "input": { "playlist_id": "1234567890" },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/youtube/community-post

**YouTube Community Post.** Returns structured JSON for **YouTube Community Post**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/youtube/community-post?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "youtube",
  "scraper": "youtube-community-post",
  "input": { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
  "data": { /* the YouTube payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Twitter / X scraper API

*Every Twitter / X scraper endpoint: 6 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/twitter

All 6 Twitter / X endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/twitter/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Twitter / X landing page](https://hproxy.com/scrapers/twitter) for examples and use cases.

#### GET /api/v1/scrape/twitter/tweets

**Twitter User Tweets.** Returns structured JSON for **Twitter User Tweets**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitter/tweets?handle=nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitter",
  "scraper": "twitter-tweets",
  "input": { "handle": "nasa" },
  "data": { /* the Twitter / X payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/twitter/profile

**Twitter / X Profile.** Returns structured JSON for **Twitter / X Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitter/profile?handle=nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitter",
  "scraper": "twitter-profile",
  "input": { "handle": "nasa" },
  "data": { /* the Twitter / X payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/twitter/tweet

**Twitter / X Tweet.** Returns structured JSON for **Twitter / X Tweet**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitter/tweet?url=https://twitter.com/nasa/status/1745510925348782269" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitter",
  "scraper": "twitter-tweet",
  "input": { "url": "https://twitter.com/nasa/status/1745510925348782269" },
  "data": { /* the Twitter / X payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/twitter/tweet-transcript

**Twitter / X Tweet Transcript.** Returns structured JSON for **Twitter / X Tweet Transcript**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitter/tweet-transcript?url=https://twitter.com/nasa/status/1745510925348782269" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitter",
  "scraper": "twitter-tweet-transcript",
  "input": { "url": "https://twitter.com/nasa/status/1745510925348782269" },
  "data": { /* the Twitter / X payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/twitter/community

**Twitter / X Community.** Returns structured JSON for **Twitter / X Community**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitter/community?url=https://twitter.com/nasa/status/1745510925348782269" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitter",
  "scraper": "twitter-community",
  "input": { "url": "https://twitter.com/nasa/status/1745510925348782269" },
  "data": { /* the Twitter / X payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/twitter/community-tweets

**Twitter / X Community Tweets.** Returns structured JSON for **Twitter / X Community Tweets**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitter/community-tweets?url=https://twitter.com/nasa/status/1745510925348782269" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitter",
  "scraper": "twitter-community-tweets",
  "input": { "url": "https://twitter.com/nasa/status/1745510925348782269" },
  "data": { /* the Twitter / X payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## LinkedIn scraper API

*Every LinkedIn scraper endpoint: 6 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/linkedin

All 6 LinkedIn endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/linkedin/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [LinkedIn landing page](https://hproxy.com/scrapers/linkedin) for examples and use cases.

#### GET /api/v1/scrape/linkedin/profile

**LinkedIn Profile.** Returns structured JSON for **LinkedIn Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/linkedin/profile?url=https://www.linkedin.com/company/google/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "linkedin",
  "scraper": "linkedin-profile",
  "input": { "url": "https://www.linkedin.com/company/google/" },
  "data": { /* the LinkedIn payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/linkedin/company

**LinkedIn Company.** Returns structured JSON for **LinkedIn Company**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/linkedin/company?url=https://www.linkedin.com/company/google/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "linkedin",
  "scraper": "linkedin-company",
  "input": { "url": "https://www.linkedin.com/company/google/" },
  "data": { /* the LinkedIn payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/linkedin/company-posts

**LinkedIn Company Posts.** Returns structured JSON for **LinkedIn Company Posts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `page` | `integer (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/linkedin/company-posts?url=https://www.linkedin.com/company/google/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "linkedin",
  "scraper": "linkedin-company-posts",
  "input": { "url": "https://www.linkedin.com/company/google/" },
  "data": { /* the LinkedIn payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/linkedin/post

**LinkedIn Post.** Returns structured JSON for **LinkedIn Post**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/linkedin/post?url=https://www.linkedin.com/company/google/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "linkedin",
  "scraper": "linkedin-post",
  "input": { "url": "https://www.linkedin.com/company/google/" },
  "data": { /* the LinkedIn payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/linkedin/ad-search

**LinkedIn Ad Library Search.** Returns structured JSON for **LinkedIn Ad Library Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `company` | `string (query)` | required | The company parameter. Send this **or** `keyword` or `companyId`. |
| `keyword` | `string (query)` | required | The keyword parameter. Send this **or** `company` or `companyId`. |
| `companyId` | `string (query)` | required | Identifier from a previous response. Send this **or** `company` or `keyword`. |
| `countries` | `string (query)` | optional | Numeric filter applied to the results. |
| `startDate` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `endDate` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `paginationToken` | `string (query)` | optional | The paginationToken parameter. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/linkedin/ad-search?company=value" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "linkedin",
  "scraper": "linkedin-ad-search",
  "input": {  },
  "data": { /* the LinkedIn payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/linkedin/ad

**LinkedIn Ad Detail.** Returns structured JSON for **LinkedIn Ad Detail**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/linkedin/ad?url=https://www.linkedin.com/company/google/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "linkedin",
  "scraper": "linkedin-ad",
  "input": { "url": "https://www.linkedin.com/company/google/" },
  "data": { /* the LinkedIn payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Google scraper API

*Every Google scraper endpoint: 4 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/google

All 4 Google endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/google/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Google landing page](https://hproxy.com/scrapers/google) for examples and use cases.

#### GET /api/v1/scrape/google/search

**Google Search Results.** Returns structured JSON for **Google Search Results**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `date_posted` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. Allowed values: `last-hour`, `last-day`, `last-week`, `last-month`, `last-year`. |
| `page` | `integer (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/google/search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "google",
  "scraper": "google-search",
  "input": { "query": "coffee" },
  "data": { /* the Google payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/google/ad-company

**Google Ad Library Company Ads.** Returns structured JSON for **Google Ad Library Company Ads**. Billed **$0.03725 per successful call** ($37.25 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `domain` | `string (query)` | required | The domain parameter. Send this **or** `advertiser_id`. |
| `advertiser_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `domain`. |
| `topic` | `string (query)` | optional | The topic parameter. Allowed values: `all`, `political`. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `start_date` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `end_date` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `platform` | `string (query)` | optional | The platform parameter. Allowed values: `google_maps`, `google_play`, `google_search`, `google_shopping`, `youtube`. |
| `format` | `string (query)` | optional | The format parameter. Allowed values: `text`, `image`, `video`. |
| `get_ad_details` | `boolean (query)` | optional | Also include ad details in the response. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/google/ad-company?domain=value" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "google",
  "scraper": "google-ad-company",
  "input": {  },
  "data": { /* the Google payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.03725,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/google/ad

**Google Ad Detail.** Returns structured JSON for **Google Ad Detail**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/google/ad?url=https://adstransparency.google.com/advertiser/AR01" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "google",
  "scraper": "google-ad",
  "input": { "url": "https://adstransparency.google.com/advertiser/AR01" },
  "data": { /* the Google payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/google/advertiser-search

**Google Advertiser Search.** Returns structured JSON for **Google Advertiser Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `region` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/google/advertiser-search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "google",
  "scraper": "google-advertiser-search",
  "input": { "query": "coffee" },
  "data": { /* the Google payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Facebook scraper API

*Every Facebook scraper endpoint: 17 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/facebook

All 17 Facebook endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/facebook/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Facebook landing page](https://hproxy.com/scrapers/facebook) for examples and use cases.

#### GET /api/v1/scrape/facebook/profile

**Facebook Profile.** Returns structured JSON for **Facebook Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `get_business_hours` | `boolean (query)` | optional | Also include business hours in the response. |
| `include_gated_profile` | `boolean (query)` | optional | Optional flag (true or false). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/profile?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-profile",
  "input": { "url": "https://www.facebook.com/nasa" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/profile-reels

**Facebook Profile Reels.** Returns structured JSON for **Facebook Profile Reels**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `next_page_id` | `string (query)` | optional | Pagination token from the previous response. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/profile-reels?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-profile-reels",
  "input": { "url": "https://www.facebook.com/nasa" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/profile-photos

**Facebook Profile Photos.** Returns structured JSON for **Facebook Profile Photos**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `next_page_id` | `string (query)` | optional | Pagination token from the previous response. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/profile-photos?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-profile-photos",
  "input": { "url": "https://www.facebook.com/nasa" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/profile-posts

**Facebook Profile Posts.** Returns structured JSON for **Facebook Profile Posts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `pageId`. |
| `pageId` | `string (query)` | required | Identifier from a previous response. Send this **or** `url`. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/profile-posts?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-profile-posts",
  "input": {  },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/profile-events

**Facebook Profile Events.** Returns structured JSON for **Facebook Profile Events**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/profile-events?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-profile-events",
  "input": { "url": "https://www.facebook.com/nasa" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/post

**Facebook Post.** Returns structured JSON for **Facebook Post**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `get_comments` | `boolean (query)` | optional | Also include comments in the response. |
| `get_transcript` | `boolean (query)` | optional | Also include transcript in the response. |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/post?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-post",
  "input": { "url": "https://www.facebook.com/nasa" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/post-transcript

**Facebook Post Transcript.** Returns structured JSON for **Facebook Post Transcript**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/post-transcript?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-post-transcript",
  "input": { "url": "https://www.facebook.com/nasa" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/post-comments

**Facebook Post Comments.** Returns structured JSON for **Facebook Post Comments**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `feedback_id`. |
| `feedback_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `url`. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/post-comments?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-post-comments",
  "input": {  },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/comment-replies

**Facebook Comment Replies.** Returns structured JSON for **Facebook Comment Replies**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `feedback_id` | `string (query)` | required | Identifier from a previous response. |
| `expansion_token` | `string (query)` | required | The expansion token parameter. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/comment-replies?feedback_id=1234567890&expansion_token=value" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-comment-replies",
  "input": { "feedback_id": "1234567890", "expansion_token": "value" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/group-posts

**Facebook Group Posts.** Returns structured JSON for **Facebook Group Posts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `group_id`. |
| `group_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `url`. |
| `sort_by` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `TOP_POSTS`, `RECENT_ACTIVITY`, `CHRONOLOGICAL`, `CHRONOLOGICAL_LISTINGS`. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/group-posts?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-group-posts",
  "input": {  },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/events-search

**Facebook Events Search.** Returns structured JSON for **Facebook Events Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/events-search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-events-search",
  "input": { "query": "coffee" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/events

**Facebook Events by City.** Returns structured JSON for **Facebook Events by City**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `time` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. Allowed values: `today`, `this_week`, `next_week`. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/events?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-events",
  "input": { "url": "https://www.facebook.com/nasa" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/event

**Facebook Event Details.** Returns structured JSON for **Facebook Event Details**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `id` | `string (query)` | required | Identifier from a previous response. Send this **or** `url`. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `id`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/event?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-event",
  "input": {  },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/ad

**Facebook Ad Library Detail.** Returns structured JSON for **Facebook Ad Library Detail**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `id` | `string (query)` | required | Identifier from a previous response. Send this **or** `url`. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `id`. |
| `get_transcript` | `boolean (query)` | optional | Also include transcript in the response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/ad?url=https://www.facebook.com/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-ad",
  "input": {  },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/ad-search

**Facebook Ad Library Search.** Returns structured JSON for **Facebook Ad Library Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `sort_by` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `total_impressions`, `relevancy_monthly_grouped`. |
| `search_type` | `string (query)` | optional | The search type parameter. Allowed values: `keyword_unordered`, `keyword_exact_phrase`. |
| `ad_type` | `string (query)` | optional | The ad type parameter. Allowed values: `all`, `political_and_issue_ads`. |
| `country` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `status` | `string (query)` | optional | The status parameter. Allowed values: `ALL`, `ACTIVE`, `INACTIVE`. |
| `media_type` | `string (query)` | optional | The media type parameter. Allowed values: `ALL`, `IMAGE`, `VIDEO`, `MEME`, `IMAGE_AND_MEME`, `NONE`. |
| `start_date` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `end_date` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/ad-search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-ad-search",
  "input": { "query": "coffee" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/ad-company

**Facebook Company Ads.** Returns structured JSON for **Facebook Company Ads**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `pageId` | `string (query)` | required | Identifier from a previous response. Send this **or** `companyName`. |
| `companyName` | `string (query)` | required | The companyName parameter. Send this **or** `pageId`. |
| `country` | `string (query)` | optional | Two-letter region/country code, e.g. US. |
| `status` | `string (query)` | optional | The status parameter. Allowed values: `ALL`, `ACTIVE`, `INACTIVE`. |
| `language` | `string (query)` | optional | Two-letter language code, e.g. en. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `media_type` | `string (query)` | optional | The media type parameter. Allowed values: `ALL`, `IMAGE`, `VIDEO`, `MEME`, `IMAGE_AND_MEME`, `NONE`. |
| `sort_by` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `total_impressions`, `relevancy_monthly_grouped`. |
| `start_date` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `end_date` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/ad-company?pageId=1234567890" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-ad-company",
  "input": {  },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/facebook/ad-companies-search

**Facebook Ad Library Company Search.** Returns structured JSON for **Facebook Ad Library Company Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/facebook/ad-companies-search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "facebook",
  "scraper": "facebook-ad-companies-search",
  "input": { "query": "coffee" },
  "data": { /* the Facebook payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Reddit scraper API

*Every Reddit scraper endpoint: 5 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/reddit

All 5 Reddit endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/reddit/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Reddit landing page](https://hproxy.com/scrapers/reddit) for examples and use cases.

#### GET /api/v1/scrape/reddit/subreddit

**Reddit Subreddit Details.** Returns structured JSON for **Reddit Subreddit Details**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `subreddit` | `string (query)` | required | Subreddit name, without the r/ prefix. Send this **or** `url`. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `subreddit`. |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/reddit/subreddit?subreddit=dataisbeautiful" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "reddit",
  "scraper": "reddit-subreddit",
  "input": {  },
  "data": { /* the Reddit payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/reddit/subreddit-posts

**Reddit Subreddit Posts.** Returns structured JSON for **Reddit Subreddit Posts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `subreddit` | `string (query)` | required | Subreddit name, without the r/ prefix. |
| `timeframe` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. Allowed values: `all`, `day`, `week`, `month`, `year`. |
| `sort` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `best`, `hot`, `new`, `top`, `rising`. |
| `after` | `string (query)` | optional | The after parameter. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/reddit/subreddit-posts?subreddit=dataisbeautiful" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "reddit",
  "scraper": "reddit-subreddit-posts",
  "input": { "subreddit": "dataisbeautiful" },
  "data": { /* the Reddit payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/reddit/comments

**Reddit Post Comments.** Returns structured JSON for **Reddit Post Comments**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/reddit/comments?url=https://www.reddit.com/r/pics/comments/1abcdef/example/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "reddit",
  "scraper": "reddit-comments",
  "input": { "url": "https://www.reddit.com/r/pics/comments/1abcdef/example/" },
  "data": { /* the Reddit payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/reddit/search

**Reddit Search.** Returns structured JSON for **Reddit Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `sort` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `relevance`, `new`, `top`, `comment_count`. |
| `timeframe` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. Allowed values: `all`, `day`, `week`, `month`, `year`. |
| `after` | `string (query)` | optional | The after parameter. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/reddit/search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "reddit",
  "scraper": "reddit-search",
  "input": { "query": "coffee" },
  "data": { /* the Reddit payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/reddit/subreddit-search

**Reddit Subreddit Search.** Returns structured JSON for **Reddit Subreddit Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `subreddit` | `string (query)` | required | Subreddit name, without the r/ prefix. |
| `query` | `string (query)` | optional | Search term or keyword. |
| `sort` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `relevance`, `hot`, `top`, `new`, `comments`. |
| `timeframe` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. Allowed values: `all`, `year`, `month`, `week`, `day`, `hour`. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/reddit/subreddit-search?subreddit=dataisbeautiful" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "reddit",
  "scraper": "reddit-subreddit-search",
  "input": { "subreddit": "dataisbeautiful" },
  "data": { /* the Reddit payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Threads scraper API

*Every Threads scraper endpoint: 5 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/threads

All 5 Threads endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/threads/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Threads landing page](https://hproxy.com/scrapers/threads) for examples and use cases.

#### GET /api/v1/scrape/threads/profile

**Threads Profile.** Returns structured JSON for **Threads Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/threads/profile?handle=zuck" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "threads",
  "scraper": "threads-profile",
  "input": { "handle": "zuck" },
  "data": { /* the Threads payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/threads/posts

**Threads User Posts.** Returns structured JSON for **Threads User Posts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `user_id` | `string (query)` | optional | Identifier from a previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/threads/posts?handle=zuck" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "threads",
  "scraper": "threads-posts",
  "input": { "handle": "zuck" },
  "data": { /* the Threads payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/threads/post

**Threads Post.** Returns structured JSON for **Threads Post**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/threads/post?url=https://www.threads.net/@zuck" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "threads",
  "scraper": "threads-post",
  "input": { "url": "https://www.threads.net/@zuck" },
  "data": { /* the Threads payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/threads/search

**Threads Search.** Returns structured JSON for **Threads Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `start_date` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `end_date` | `string (query)` | optional | Filter by date, as YYYY-MM-DD. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/threads/search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "threads",
  "scraper": "threads-search",
  "input": { "query": "coffee" },
  "data": { /* the Threads payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/threads/search-users

**Threads Search Users.** Returns structured JSON for **Threads Search Users**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/threads/search-users?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "threads",
  "scraper": "threads-search-users",
  "input": { "query": "coffee" },
  "data": { /* the Threads payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Bluesky scraper API

*Every Bluesky scraper endpoint: 3 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/bluesky

All 3 Bluesky endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/bluesky/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Bluesky landing page](https://hproxy.com/scrapers/bluesky) for examples and use cases.

#### GET /api/v1/scrape/bluesky/profile

**Bluesky Profile.** Returns structured JSON for **Bluesky Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/bluesky/profile?handle=bsky.app" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "bluesky",
  "scraper": "bluesky-profile",
  "input": { "handle": "bsky.app" },
  "data": { /* the Bluesky payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/bluesky/posts

**Bluesky User Posts.** Returns structured JSON for **Bluesky User Posts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `user_id`. |
| `user_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/bluesky/posts?handle=bsky.app" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "bluesky",
  "scraper": "bluesky-posts",
  "input": {  },
  "data": { /* the Bluesky payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/bluesky/post

**Bluesky Post.** Returns structured JSON for **Bluesky Post**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/bluesky/post?url=https://bsky.app/profile/bsky.app" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "bluesky",
  "scraper": "bluesky-post",
  "input": { "url": "https://bsky.app/profile/bsky.app" },
  "data": { /* the Bluesky payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Truth Social scraper API

*Every Truth Social scraper endpoint: 3 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/truth-social

All 3 Truth Social endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/truth-social/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Truth Social landing page](https://hproxy.com/scrapers/truth-social) for examples and use cases.

#### GET /api/v1/scrape/truth-social/profile

**Truth Social Profile.** Returns structured JSON for **Truth Social Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/truth-social/profile?handle=realDonaldTrump" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "truth-social",
  "scraper": "truth-social-profile",
  "input": { "handle": "realDonaldTrump" },
  "data": { /* the Truth Social payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/truth-social/posts

**Truth Social User Posts.** Returns structured JSON for **Truth Social User Posts**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `user_id`. |
| `user_id` | `string (query)` | required | Identifier from a previous response. Send this **or** `handle`. |
| `next_max_id` | `string (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/truth-social/posts?handle=realDonaldTrump" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "truth-social",
  "scraper": "truth-social-posts",
  "input": {  },
  "data": { /* the Truth Social payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/truth-social/post

**Truth Social Post.** Returns structured JSON for **Truth Social Post**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/truth-social/post?url=https://truthsocial.com/@realDonaldTrump" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "truth-social",
  "scraper": "truth-social-post",
  "input": { "url": "https://truthsocial.com/@realDonaldTrump" },
  "data": { /* the Truth Social payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Pinterest scraper API

*Every Pinterest scraper endpoint: 4 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/pinterest

All 4 Pinterest endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/pinterest/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Pinterest landing page](https://hproxy.com/scrapers/pinterest) for examples and use cases.

#### GET /api/v1/scrape/pinterest/search

**Pinterest Search.** Returns structured JSON for **Pinterest Search**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `query` | `string (query)` | required | Search term or keyword. |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/pinterest/search?query=coffee" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "pinterest",
  "scraper": "pinterest-search",
  "input": { "query": "coffee" },
  "data": { /* the Pinterest payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/pinterest/pin

**Pinterest Pin.** Returns structured JSON for **Pinterest Pin**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/pinterest/pin?url=https://www.pinterest.com/pin/1234567890/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "pinterest",
  "scraper": "pinterest-pin",
  "input": { "url": "https://www.pinterest.com/pin/1234567890/" },
  "data": { /* the Pinterest payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/pinterest/boards

**Pinterest User Boards.** Returns structured JSON for **Pinterest User Boards**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/pinterest/boards?handle=nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "pinterest",
  "scraper": "pinterest-boards",
  "input": { "handle": "nasa" },
  "data": { /* the Pinterest payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/pinterest/board

**Pinterest Board Pins.** Returns structured JSON for **Pinterest Board Pins**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `cursor` | `string (query)` | optional | Pagination token from the previous response. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/pinterest/board?url=https://www.pinterest.com/pin/1234567890/" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "pinterest",
  "scraper": "pinterest-board",
  "input": { "url": "https://www.pinterest.com/pin/1234567890/" },
  "data": { /* the Pinterest payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Twitch scraper API

*Every Twitch scraper endpoint: 4 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/twitch

All 4 Twitch endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/twitch/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Twitch landing page](https://hproxy.com/scrapers/twitch) for examples and use cases.

#### GET /api/v1/scrape/twitch/profile

**Twitch Profile.** Returns structured JSON for **Twitch Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitch/profile?handle=twitch" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitch",
  "scraper": "twitch-profile",
  "input": { "handle": "twitch" },
  "data": { /* the Twitch payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/twitch/videos

**Twitch User Videos.** Returns structured JSON for **Twitch User Videos**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `filter_by` | `string (query)` | optional | The filter by parameter. Allowed values: `HIGHLIGHT`, `ARCHIVE`, `UPLOAD`. |
| `sort_by` | `string (query)` | optional | Ordering to apply to the results. Allowed values: `TIME`, `VIEWS`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitch/videos?handle=twitch" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitch",
  "scraper": "twitch-videos",
  "input": { "handle": "twitch" },
  "data": { /* the Twitch payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/twitch/clip

**Twitch Clip.** Returns structured JSON for **Twitch Clip**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitch/clip?url=https://www.twitch.tv/twitch" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitch",
  "scraper": "twitch-clip",
  "input": { "url": "https://www.twitch.tv/twitch" },
  "data": { /* the Twitch payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/twitch/schedule

**Twitch User Schedule.** Returns structured JSON for **Twitch User Schedule**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/twitch/schedule?handle=twitch" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "twitch",
  "scraper": "twitch-schedule",
  "input": { "handle": "twitch" },
  "data": { /* the Twitch payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Snapchat scraper API

*Every Snapchat scraper endpoint: 1 action returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/snapchat

All 1 Snapchat endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/snapchat/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Snapchat landing page](https://hproxy.com/scrapers/snapchat) for examples and use cases.

#### GET /api/v1/scrape/snapchat/profile

**Snapchat Profile.** Returns structured JSON for **Snapchat Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/snapchat/profile?handle=team.snapchat" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "snapchat",
  "scraper": "snapchat-profile",
  "input": { "handle": "team.snapchat" },
  "data": { /* the Snapchat payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Spotify scraper API

*Every Spotify scraper endpoint: 3 actions returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/spotify

All 3 Spotify endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/spotify/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Spotify landing page](https://hproxy.com/scrapers/spotify) for examples and use cases.

#### GET /api/v1/scrape/spotify/artist

**Spotify Artist.** Returns structured JSON for **Spotify Artist**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `id` | `string (query)` | required | Identifier from a previous response. Send this **or** `url`. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `id`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/spotify/artist?url=https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "spotify",
  "scraper": "spotify-artist",
  "input": {  },
  "data": { /* the Spotify payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/spotify/track

**Spotify Track.** Returns structured JSON for **Spotify Track**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `id` | `string (query)` | required | Identifier from a previous response. Send this **or** `url`. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `id`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/spotify/track?url=https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "spotify",
  "scraper": "spotify-track",
  "input": {  },
  "data": { /* the Spotify payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

#### GET /api/v1/scrape/spotify/album

**Spotify Album.** Returns structured JSON for **Spotify Album**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `id` | `string (query)` | required | Identifier from a previous response. Send this **or** `url`. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `id`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/spotify/album?url=https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "spotify",
  "scraper": "spotify-album",
  "input": {  },
  "data": { /* the Spotify payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## SoundCloud scraper API

*Every SoundCloud scraper endpoint: 1 action returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/soundcloud

All 1 SoundCloud endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/soundcloud/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [SoundCloud landing page](https://hproxy.com/scrapers/soundcloud) for examples and use cases.

#### GET /api/v1/scrape/soundcloud/artist

**SoundCloud Artist.** Returns structured JSON for **SoundCloud Artist**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `handle` | `string (query)` | required | Account handle or @username. Send this **or** `url`. |
| `url` | `url (query)` | required | Target URL (profile, post or video). Send this **or** `handle`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/soundcloud/artist?handle=soundcloud" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "soundcloud",
  "scraper": "soundcloud-artist",
  "input": {  },
  "data": { /* the SoundCloud payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Kick scraper API

*Every Kick scraper endpoint: 1 action returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/kick

All 1 Kick endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/kick/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Kick landing page](https://hproxy.com/scrapers/kick) for examples and use cases.

#### GET /api/v1/scrape/kick/clip

**Kick Clip.** Returns structured JSON for **Kick Clip**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/kick/clip?url=https://kick.com/trainwreckstv" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "kick",
  "scraper": "kick-clip",
  "input": { "url": "https://kick.com/trainwreckstv" },
  "data": { /* the Kick payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Linktree scraper API

*Every Linktree scraper endpoint: 1 action returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/linktree

All 1 Linktree endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/linktree/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Linktree landing page](https://hproxy.com/scrapers/linktree) for examples and use cases.

#### GET /api/v1/scrape/linktree/page

**Linktree Page.** Returns structured JSON for **Linktree Page**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/linktree/page?url=https://linktr.ee/nasa" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "linktree",
  "scraper": "linktree-page",
  "input": { "url": "https://linktr.ee/nasa" },
  "data": { /* the Linktree payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Komi scraper API

*Every Komi scraper endpoint: 1 action returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/komi

All 1 Komi endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/komi/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Komi landing page](https://hproxy.com/scrapers/komi) for examples and use cases.

#### GET /api/v1/scrape/komi/page

**Komi Page.** Returns structured JSON for **Komi Page**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/komi/page?url=https://komi.io/komi" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "komi",
  "scraper": "komi-page",
  "input": { "url": "https://komi.io/komi" },
  "data": { /* the Komi payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Pillar scraper API

*Every Pillar scraper endpoint: 1 action returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/pillar

All 1 Pillar endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/pillar/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Pillar landing page](https://hproxy.com/scrapers/pillar) for examples and use cases.

#### GET /api/v1/scrape/pillar/page

**Pillar Page.** Returns structured JSON for **Pillar Page**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/pillar/page?url=https://pillar.io/pillar" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "pillar",
  "scraper": "pillar-page",
  "input": { "url": "https://pillar.io/pillar" },
  "data": { /* the Pillar payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Lnk.Bio scraper API

*Every Lnk.Bio scraper endpoint: 1 action returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/linkbio

All 1 Lnk.Bio endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/linkbio/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Lnk.Bio landing page](https://hproxy.com/scrapers/linkbio) for examples and use cases.

#### GET /api/v1/scrape/linkbio/page

**Linkbio Page.** Returns structured JSON for **Linkbio Page**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/linkbio/page?url=https://lnk.bio/linkbio" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "linkbio",
  "scraper": "linkbio-page",
  "input": { "url": "https://lnk.bio/linkbio" },
  "data": { /* the Lnk.Bio payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Linkme scraper API

*Every Linkme scraper endpoint: 1 action returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/linkme

All 1 Linkme endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/linkme/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Linkme landing page](https://hproxy.com/scrapers/linkme) for examples and use cases.

#### GET /api/v1/scrape/linkme/page

**Linkme Profile.** Returns structured JSON for **Linkme Profile**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |
| `cache_max_age` | `string (query)` | optional | Accept a cached result up to this old (1d, 3d, 7d, 14d or 30d) and pay nothing for it. Omit for a live scrape. Allowed values: `1d`, `3d`, `7d`, `14d`, `30d`. |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/linkme/page?url=https://link.me/linkme" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "linkme",
  "scraper": "linkme-page",
  "input": { "url": "https://link.me/linkme" },
  "data": { /* the Linkme payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

## Amazon scraper API

*Every Amazon scraper endpoint: 1 action returning structured JSON from $0.00149 per call. No proxies, no captchas, no infrastructure.*

URL: https://hproxy.com/docs/scrapers/amazon

All 1 Amazon endpoints, from **$0.00149 per call**. Each is callable as `GET https://hproxy.com/api/v1/scrape/amazon/{action}` (or `POST` with a JSON body) using a key with the `scrape` scope. No proxies, captchas or parsing to manage, it is all included in the price, and errors, timeouts and rate limits are never billed. See the [full catalog](https://hproxy.com/docs/scrapers/catalog) for every platform, or the [Amazon landing page](https://hproxy.com/scrapers/amazon) for examples and use cases.

#### GET /api/v1/scrape/amazon/shop

**Amazon Shop Page.** Returns structured JSON for **Amazon Shop Page**. Billed **$0.00149 per successful call** ($1.49 per 1,000); errors, timeouts and rate limits are never charged, while a lookup whose target does not exist is billed like a successful call because the platform was queried. `POST` with a JSON body works too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `x-api-key` | `string (header)` | required | Your HProxy API key with the scrape scope. |
| `url` | `url (query)` | required | Target URL (profile, post or video). |
| `trim` | `boolean (query)` | optional | Return a slimmed-down payload (drops verbose fields). |

**cURL**

```bash
curl "https://hproxy.com/api/v1/scrape/amazon/shop?url=https://www.amazon.com/stores/page/EXAMPLE" \
  -H "X-API-Key: hpx_your_key_here"
```

**Response**

```json
{
  "platform": "amazon",
  "scraper": "amazon-shop",
  "input": { "url": "https://www.amazon.com/stores/page/EXAMPLE" },
  "data": { /* the Amazon payload, as structured JSON */ },
  "records": 1,
  "costUsd": 0.00149,
  "walletDebitUsd": 0,
  "requestId": "c4389b749c07d44209e4fb301",
  "elapsedMs": 812
}
```

---

# Free Proxy List

## Free proxy list API

*GET /api/proxy-list returns every working free proxy we have, as txt, JSON or CSV. No key, CORS enabled, filterable by country, protocol, anonymity, network (ASN), port and /24 subnet.*

URL: https://hproxy.com/docs/free-proxy-list

#### GET /api/proxy-list (no key)

**The whole live list in one call.** One GET returns **every working proxy we have**, as `txt`, `json` or `csv`. Not a sample and not a teaser: HTTP, HTTPS, SOCKS4 and SOCKS5, all of it, in a single call. No key, no signup. CORS is enabled, so you can call it straight from a browser. Fair-use rate limit of about 120 requests per minute per IP, with bursts up to 120 (a clean `429` with `Retry-After` beyond that). This is the same data behind the [free proxy list](https://hproxy.com/free-proxy-list).

**How many is that?** Thousands at any moment, and tens of thousands within two days, because that is how many public proxies on Earth are actually answering. It moves every few minutes as proxies die and new ones are found, so treat any number written here as a rough order of magnitude and never as the truth. `X-Total-Available` on the response is the exact count matching your filter, and `X-Total-Count` is how many came back in this particular response. If the two are equal you already have everything and there is no next page.

**Why you will see 10,000 mentioned below.** That is the most rows a single response will carry *when you ask for a specific number*. It is a page size, not a cap on what you are allowed to have. **Omit `limit` entirely and you get the complete matching set in one response**, however large it is. The page size only comes into play when you pass `limit` yourself, or on a set big enough that we page it for you (`recent=true`).

| Field | Type | Description |
| --- | --- | --- |
| `format` | `txt | json | csv` | Response shape. Default txt (one ip:port per line). |
| `protocol` | `http | https | socks4 | socks5` | Filter by protocol. Comma-separated allowed (e.g. http,https), which matches a proxy supporting ANY of them. |
| `country` | `ISO-3166 alpha-2` | Filter by country, e.g. US, DE, GB. |
| `anonymity` | `elite | anonymous | transparent` | Filter by anonymity grade. Proxies we have not been able to grade yet are excluded. |
| `asn` | `number` | Filter by autonomous system, e.g. 14061 for DigitalOcean. Same data as the per-network pages on the free list. |
| `port` | `1 - 65535` | Only proxies answering on this exact port, e.g. 8080 or 1080. |
| `subnet` | `a.b.c (first three octets)` | Only proxies inside one /24 block, e.g. subnet=45.61.188 for 45.61.188.0/24. Open proxies cluster in blocks, so this finds a machine's neighbors. |
| `min_uptime_pct` | `0 - 100` | Only proxies whose lifetime uptime is at least this. The single most useful filter if you want proxies that stay up. |
| `max_latency_ms` | `1 - 120000` | Only proxies at or below this latency, in milliseconds. |
| `sort` | `uptime` | Order the whole pool by reliability before paging, so page 1 is the best proxies overall. Omit for the default order (alive first, then fastest). |
| `limit` | `1 - 10000` | Rows in THIS response, not a limit on your total. Leave it out and you receive the complete matching set in one call, which is what most callers want. Pass a number and this response stops at that many rows (10000 is the ceiling for one response); use offset to walk the rest. Whatever you do, X-Total-Available still reports how many exist. |
| `offset` | `0+` | Skip this many rows. Needed only when you passed an explicit limit, or on a set too large for one response. Default 0. |
| `recent` | `true | false` | Also include proxies that have gone quiet but answered within the last 48h, taking the set from the live-now pool to several times its size. This WIDENS the list, it does not freshen it: the extra rows come back with status recently_alive and many are not answering right now. Leave it off for the strictly alive-now pool. |

**cURL**

```bash
curl "https://hproxy.com/api/proxy-list?format=json&country=US&protocol=socks5"
```

**Python**

```python
import requests

# The most reliable proxies first: at least 70% lifetime uptime,
# under a second, ordered by reliability across the whole pool.
r = requests.get("https://hproxy.com/api/proxy-list", params={
    "format": "json",
    "protocol": "http,socks5",
    "min_uptime_pct": 70,
    "max_latency_ms": 1000,
    "sort": "uptime",
    "limit": 200,
})
proxies = r.json()
print(len(proxies), "of", r.headers["X-Total-Available"], "matching proxies")
```

**Node.js**

```js
// Page through everything that matches, 5000 at a time.
const all = [];
for (let offset = 0; ; offset += 5000) {
  const res = await fetch(
    `https://hproxy.com/api/proxy-list?format=json&protocol=https&limit=5000&offset=${offset}`
  );
  const page = await res.json();
  all.push(...page);
  if (all.length >= Number(res.headers.get("X-Total-Available"))) break;
}
console.log(all.length, "proxies");
```

**JSON row**

```json
{
  "ip": "203.0.113.7",
  "port": 1080,
  "protocols": ["socks4", "socks5"],
  "anonymity": "elite",
  "country_code": "US",
  "region": "New York",
  "city": "New York",
  "latitude": 40.71,
  "longitude": -74.0,
  "asn": 14061,
  "asn_org": "DigitalOcean, LLC",
  "is_datacenter": true,
  "latency_ms": 142,
  "last_verified_at": "2026-07-22T15:41:09Z",
  "last_alive_at": "2026-07-22T15:41:09Z",
  "status": "alive",
  "uptime_pct": 71.4,
  "uptime_24h": 83.3,
  "uptime_7d": 74.9,
  "status_since": "2026-07-22T09:12:00Z",
  "reliability": "flaky",
  "verification_count": 321
}
```

The `json` format returns an array of full objects (geo, ASN, latency, uptime and last-checked timestamps; fields the engine hasn't enriched yet are `null`, never fabricated). `txt` is one `ip:port` per line, easiest to pipe into tools. `csv` is spreadsheet-ready with a header row.

Every row carries how the proxy has actually been behaving, so you can judge it before you use it: `status` is `alive` when it is passing checks right now, `uptime_pct` is its lifetime success rate, `uptime_24h` and `uptime_7d` are the recent windows, and `verification_count` is how many times we have tested it. Filter on those with `min_uptime_pct`, or hand the ordering to us with `sort=uptime`. Rows with `status: "recently_alive"` only ever appear when you pass `recent=true`, and mean the proxy has stopped answering but was up within the last 48 hours.

> [!NOTE] **Use it from an AI assistant**: AI assistants can call this as the `proxy_list` tool of HProxy's MCP server: add `https://mcp.hproxy.com/mcp` as a remote MCP server, nothing to install and no key. The line for each assistant (Claude, ChatGPT, Cursor, VS Code and more) is on [/tools/ai](https://hproxy.com/tools/ai), and the tools in full are in [the MCP server docs](https://hproxy.com/docs/free/mcp-server).

> [!TIP] **Need proxies that don't die?**: Free proxies are shared and unstable by nature. HProxy residential, ISP and mobile proxies stay up, from $0.18/GB. [See plans →](https://hproxy.com/pricing)

---

# Free Tools

## Proxy checker API

*GET or POST https://hproxy.com/api/proxy-check runs a real live test on any proxy: alive, protocols, anonymity, latency and location. Free, no key.*

URL: https://hproxy.com/docs/free/proxy-checker

#### GET /api/proxy-check (no key)

**Check one proxy.** Check whether a proxy is alive and get its protocols, anonymity grade, latency and location. Free, no key, CORS enabled. Each request runs a **real live test** against the proxy (a dead one can take a few seconds to report).

Two limits apply, and every checker endpoint shares them. **Requests**: 120 in a burst per IP, then 5 a second. **Proxies checked**: 300,000 a day per IP, refilling continuously. A signed-in account, or an [API key](#free-proxy-check-keyed), gets ten times both. Past either you get a `429` with `Retry-After` and a `code` saying which limit it was (`rate_limited`, `daily_budget`, or `busy` when the whole service is at capacity). Every answer reports the daily budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Cost`, so you can pace yourself from the headers.

`status` is the verdict: `alive`, `dead`, `invalid` (we could not read the line), `unresolved` (the hostname has no DNS answer), `forbidden` (a private or reserved address we do not dial) or `unchecked` (no answer inside the time budget; not a verdict, retry the line). For a gateway proxy, `exit_ip` is where your traffic actually comes out, and the location fields describe that address. A dead proxy carries the reason in `failure` (`refused`, `timeout`, `tls_error`, `bad_status`, `no_echo`). Geo and ASN fields fill in when enrichment data exists and are `null` otherwise.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `proxy` | `ip:port (query)` | required | The proxy to test, e.g. 203.0.113.7:1080, or host:port:user:pass for one with a login. |

**Request**

```bash
curl "https://hproxy.com/api/proxy-check?proxy=203.0.113.7:1080"
```

**Response**

```json
{
  "input": "203.0.113.7:1080",
  "status": "alive",
  "alive": true,
  "ip": "203.0.113.7",
  "exit_ip": "203.0.113.7",
  "port": 1080,
  "protocols": ["socks5"],
  "anonymity": "elite",
  "latency_ms": 184,
  "country_code": "US",
  "region": "New York",
  "city": "New York",
  "asn": 14061,
  "asn_org": "DigitalOcean, LLC",
  "is_datacenter": true,
  "failure": null,
  "error": null
}
```

#### POST /api/proxy-check (no key)

**Check up to 1,000 at once.** POST a JSON body with up to **1,000** proxies. They are checked in parallel and the answer comes back in one response within about 25 seconds: a few seconds when they are alive, longer when some never answer. The response is `{ "count": n, "results": [ ... ], "complete": true, "unchecked": 0 }` with the same per-proxy shape, one row for **every** line you sent. A line that did not get an answer inside the time budget comes back with `status: "unchecked"`, and `complete` is then `false`: retry those lines, or stream the list instead. Bigger lists belong on the streaming endpoint below, which takes up to 100,000 and reports each proxy the moment it settles.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `proxies` | `string[]` | required | Up to 1,000 proxy lines per request (ip:port, host:port:user:pass or user:pass@host:port). |

**Request**

```bash
curl -X POST https://hproxy.com/api/proxy-check \
  -H "Content-Type: application/json" \
  -d '{"proxies": ["203.0.113.7:1080", "198.51.100.3:8080"]}'
```

**Response**

```json
{
  "count": 2,
  "results": [
    { "input": "203.0.113.7:1080", "status": "alive", "alive": true, "ip": "203.0.113.7", "port": 1080, "protocols": ["socks5"], "latency_ms": 184, "failure": null, "error": null },
    { "input": "198.51.100.3:8080", "status": "dead", "alive": false, "ip": "198.51.100.3", "port": 8080, "protocols": [], "latency_ms": null, "failure": "timeout", "error": "proxy did not respond" }
  ],
  "complete": true,
  "unchecked": 0
}
```

#### POST /api/free-proxy/check (no key)

**Stream a big list, up to 100,000.** The endpoint behind our [online proxy checker](https://hproxy.com/proxy-checker-online) page. POST the list and read the answer as **NDJSON**: one JSON line per proxy, in the shape above, written the moment that proxy settles, so you can show results while the rest are still running. The same limits apply, counted per proxy.

Two kinds of event lines ride along; skip any line that has an `_event` key you do not know. `{"_event":"progress","done":N,"total":M}` arrives every 15 seconds, and `{"_event":"end","total":M,"done":M,"duration_ms":N}` closes a finished batch. **A stream that stops without the end line was cut** (a network drop, or a restart on our side): the lines you have no row for were not checked, so send just those again.

If your list is big enough that the run takes minutes, hand it over as a [job](#check-jobs-create) instead: nothing stays connected, and an interrupted job resumes by itself.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `proxies` | `string[]` | required | Up to 100,000 proxy lines. |
| `timeout_ms` | `integer` | optional | Per-probe budget, 1,000 to 60,000. Default 8,000. |
| `retries` | `integer` | optional | Extra attempts for a proxy that does not answer, 0 to 3. Default 0. |
| `protocols` | `string[]` | optional | Any of http, https, socks4, socks5. Default all four. |
| `measure_speed` | `boolean` | optional | Also measure download speed through each working proxy (speed_mbps). |
| `measure_udp` | `boolean` | optional | Also test whether each working SOCKS5 proxy relays UDP (supports_udp). |

**Request**

```bash
curl -N -X POST https://hproxy.com/api/free-proxy/check \
  -H "Content-Type: application/json" \
  -d '{"proxies": ["203.0.113.7:1080", "198.51.100.3:8080"], "protocols": ["socks5"]}'
```

**Response (NDJSON)**

```json
{"input":"203.0.113.7:1080","status":"alive","alive":true,"ip":"203.0.113.7","port":1080,"protocols":["socks5"],"latency_ms":184,"failure":null,"error":null}
{"input":"198.51.100.3:8080","status":"dead","alive":false,"ip":"198.51.100.3","port":8080,"protocols":[],"latency_ms":null,"failure":"refused","error":"proxy did not respond"}
{"_event":"end","total":2,"done":2,"duration_ms":2391}
```

#### POST /api/v1/free-proxy/check

**With your API key.** Every checker endpoint also answers under `/api/v1` for an API key: `POST /api/v1/free-proxy/check` streams, `GET` and `POST /api/v1/proxy-check` answer in one response. Same bodies, same result rows, and your account's tier: ten times the requests and 3,000,000 proxies a day, counted on the account rather than on the address, so a whole team behind one office connection is not squeezed into one person's budget. Any key works; checking spends nothing and needs no scope. Errors come back in the usual `/api/v1` shape, `{ "error", "code" }`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key (or Authorization: Bearer hpx_...). |

**Request**

```bash
curl -N -X POST https://hproxy.com/api/v1/free-proxy/check \
  -H "X-API-Key: hpx_..." -H "Content-Type: application/json" \
  -d '{"proxies": ["gate.example.com:7000:user:pass"]}'
```

#### POST /api/v1/proxy-check/jobs

**Hand over a big list as a job.** For the lists that take minutes: hand the list over, get an id back immediately, come back for the results when it is done. Nothing has to stay connected, so a dropped line, a closed laptop or a restart on our side does not cost you the run — a job that is interrupted resumes on the line after the last one answered.

**Accounts only** (an API key, or signed in on the dashboard). The list costs the same as checking it any other way: every line is charged to your daily budget of 3,000,000 when the job is created, and refunded if the job could not be created at all.

The limits that keep this from becoming a flood: up to **100,000** lines per job, **3** queued or running jobs at a time per account, and 20 job creations an hour. Job probes run in the lowest lane, below every live check, so they pause while the service is under load and pick up again by themselves. Results live for **72 hours** after the job ends, then the files are deleted and the job reads `expired`.

Send the list as `{ "proxies": [...] }` with the same options the streaming endpoint takes, or as a `text/plain` body of one proxy per line (what `curl --data-binary @list.txt` sends). Answer is `202` with the job.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key (or Authorization: Bearer hpx_...). |
| `proxies` | `string[]` | required | Up to 100,000 proxy lines. A text/plain body of one line per proxy works too. |
| `label` | `string` | optional | Your own name for the run, up to 64 characters. Shown in the dashboard. |
| `timeout_ms` | `integer` | optional | Per-probe budget, 1,000 to 60,000. Default 8,000. |
| `retries` | `integer` | optional | Extra attempts for a proxy that does not answer, 0 to 3. Default 0. |
| `protocols` | `string[]` | optional | Any of http, https, socks4, socks5. Default all four. |
| `measure_speed` | `boolean` | optional | Also measure download speed through each working proxy (speed_mbps). |
| `measure_udp` | `boolean` | optional | Also test whether each working SOCKS5 proxy relays UDP (supports_udp). |

**Request**

```bash
curl -X POST https://hproxy.com/api/v1/proxy-check/jobs \
  -H "X-API-Key: hpx_..." -H "Content-Type: text/plain" \
  --data-binary @list.txt
```

**Response**

```json
{
  "id": "cj_7f1c0e5a4b3d4f0e9a2c6b8d1e3f5a70",
  "status": "queued",
  "total": 41000,
  "done": 0,
  "alive": 0,
  "label": null,
  "created_at": "2026-09-12T10:04:11Z",
  "started_at": null,
  "finished_at": null,
  "expires_at": null,
  "error": null,
  "results_url": "/api/v1/proxy-check/jobs/cj_7f1c0e5a4b3d4f0e9a2c6b8d1e3f5a70/results",
  "queue_position": 1
}
```

#### GET /api/v1/proxy-check/jobs/{id}

**Watch a job.** The same job body, with `done` and `alive` climbing as lines settle. `status` is `queued` (with `queue_position` while it waits), `running`, `done`, `cancelled`, `failed` (the reason is in `error`) or `expired` (the results have been deleted). Poll it every few seconds, not every few milliseconds — it counts against your request limit like any other call.

`GET /api/v1/proxy-check/jobs` lists your 20 most recent jobs as `{ "count": n, "jobs": [ ... ] }`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key. |
| `id` | `string (path)` | required | The job id you got back from the create call. |

**Request**

```bash
curl https://hproxy.com/api/v1/proxy-check/jobs/cj_7f1c0e5a... \
  -H "X-API-Key: hpx_..."
```

**Response**

```json
{
  "id": "cj_7f1c0e5a4b3d4f0e9a2c6b8d1e3f5a70",
  "status": "running",
  "total": 41000,
  "done": 18734,
  "alive": 2211,
  "started_at": "2026-09-12T10:04:13Z",
  "finished_at": null,
  "expires_at": null,
  "error": null,
  "results_url": "/api/v1/proxy-check/jobs/cj_7f1c0e5a4b3d4f0e9a2c6b8d1e3f5a70/results"
}
```

#### GET /api/v1/proxy-check/jobs/{id}/results

**Download the results.** Everything that has settled, in the format you ask for. It works on a running job too, so you can start reading before the list is finished — and reading does not consume anything: the file stays until the job expires, so you can download it as often as you like.

`format=ndjson` (the default) is one result row per line, the exact shape every checker endpoint returns. `format=txt` is the working proxies only, one line per proxy, ready to paste straight back into whatever you feed proxies to. `format=csv` is a spreadsheet with a header row. Add `only=alive` to drop the dead rows from any format. `txt` and `csv` come back as a download; ndjson streams.

After the retention window the job reads `expired` and this answers `410`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key. |
| `format` | `ndjson | txt | csv` | optional | Default ndjson. txt is the working proxies only; csv carries a header row. |
| `only` | `alive` | optional | Drop the dead rows (txt does this anyway). |

**Request**

```bash
# the working ones, ready to use
curl "https://hproxy.com/api/v1/proxy-check/jobs/cj_7f1c0e5a.../results?format=txt" \
  -H "X-API-Key: hpx_..." -o working.txt
```

**Response (NDJSON)**

```json
{"input":"203.0.113.7:1080","status":"alive","alive":true,"protocols":["socks5"],"exit_ip":"203.0.113.7","anonymity":"elite","latency_ms":184,"country_code":"US","city":"New York","asn":14061,"asn_org":"DigitalOcean, LLC","is_datacenter":true,"failure":null}
{"input":"198.51.100.3:8080","status":"dead","alive":false,"protocols":[],"failure":"timeout"}
```

#### DELETE /api/v1/proxy-check/jobs/{id}

**Cancel a job.** Stops a queued or running job. What it already answered stays downloadable until it expires, so canceling a long run is a fine way to say "that is enough of these". A job that has already finished answers `409`; the lines it did not get to are not refunded.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `X-API-Key` | `header` | required | Your hpx_ key. |
| `id` | `string (path)` | required | The job to stop. |

**Request**

```bash
curl -X DELETE https://hproxy.com/api/v1/proxy-check/jobs/cj_7f1c0e5a... \
  -H "X-API-Key: hpx_..."
```

> [!NOTE] **Your proxies stay yours.** The checker tests the proxies you send and returns the results. They are never saved or added to our [free list](https://hproxy.com/free-proxy-list). A job's list and results sit on our disk only until the job expires, then both files are deleted.

> [!NOTE] **Use it from an AI assistant**: AI assistants can call this as the `proxy_check` tool of HProxy's MCP server: add `https://mcp.hproxy.com/mcp` as a remote MCP server, nothing to install and no key. The line for each assistant (Claude, ChatGPT, Cursor, VS Code and more) is on [/tools/ai](https://hproxy.com/tools/ai), and the tools in full are in [the MCP server docs](https://hproxy.com/docs/free/mcp-server).

## IP location and ASN API

*GET https://hproxy.com/api/ip/{ip} returns country, region, city, coordinates, timezone, ASN and ISP for any public IP. Free, no key, CORS enabled, batch supported.*

URL: https://hproxy.com/docs/free/ip-lookup

#### GET /api/ip/{ip} (no key)

**Location and network for any IP.** One GET returns where an IP is and which network runs it: country, region, city, coordinates, timezone, ASN, ASN organization and ISP. No key, no signup, CORS enabled so you can call it straight from a browser or an extension.

This is the same lookup that powers the [free proxy list](https://hproxy.com/free-proxy-list) and our own [proxy checker](https://hproxy.com/proxy-checker), so if you are writing a proxy checker of your own, you can label your results with exactly the data we label ours with. It is read from offline databases, so there is no third-party API in the path.

Two limits apply per IP, and they are deliberately separate. **Requests** on this single-address door are capped at 900 in a burst, refilling 30 per second. **Addresses** are capped by the budget described under the batch endpoint below, and both doors draw on that same budget, so a hundred thousand single lookups cost exactly what one batch of a hundred thousand costs. Every answer reports the address budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Cost`, so you can pace yourself from the headers rather than discovering the limit by being refused. Past either one you get a clean `429` with `Retry-After`.

Responses carry `Cache-Control: public, max-age=21600`: an address's location and ASN move on the order of weeks, so cache them hard rather than re-asking on every run.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ip` | `IPv4 or IPv6` | required | The address to look up, in the path. Private, loopback, link-local, CGNAT and other reserved ranges are rejected with 400 private_ip, because they have no public location. |

**cURL**

```bash
curl "https://hproxy.com/api/ip/45.79.12.44"
```

**Response**

```json
{
  "ip": "45.79.12.44",
  "country": "US",
  "country_name": "United States",
  "region": "Texas",
  "city": "Dallas",
  "latitude": 32.7797,
  "longitude": -96.8022,
  "timezone": "America/Chicago",
  "asn": 63949,
  "asn_org": "Akamai Technologies, Inc.",
  "isp": "Akamai Technologies, Inc.",
  "is_datacenter": false
}
```

**Python**

```python
import requests

r = requests.get("https://hproxy.com/api/ip/45.79.12.44")
geo = r.json()
print(geo["city"], geo["country"], "AS%s" % geo["asn"], geo["asn_org"])
```

#### POST /api/ip (no key)

**Batch: up to 100 000 addresses per call.** If you are labeling a whole proxy list, use this instead of one request per proxy. Send up to **100,000** addresses in one call and get one result per address, **in the same order you sent them**, so you can zip the two lists together without matching on anything.

**You are charged per distinct address, not per request and not per line.** Duplicates are free, because they are free for us: a list that repeats one host across twenty ports is one lookup on our side, so it is one address on your budget, and there is no need to deduplicate before sending. Lines we reject as invalid or private are free for the same reason, since they never reach the lookup at all. Your budget per IP is 120,000 addresses in a burst, refilling 1,000 per second, and 2,000,000 per day.

**Large batches stream.** The response starts arriving as soon as the first addresses resolve rather than after the last one, which is what makes a call this size practical. It is still a single JSON document with a single `results` array in your original order, so `res.json()` and `r.json()` keep working exactly as before; the bytes simply arrive in pieces. Budget a couple of minutes for a fully cold 100 000-address batch. Anything we have looked up in the last six hours comes back from cache, so a list you re-check is far faster than the first run.

Addresses that cannot be resolved come back as `{ "ip": "…", "found": false }` rather than being dropped, so the arrays always line up.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ips` | `string[]` | required | Up to 100 000 IP addresses. A bare JSON array is also accepted. More than 100 000 returns 400 batch_too_large. |

**cURL**

```bash
curl -X POST "https://hproxy.com/api/ip" \
  -H "content-type: application/json" \
  -d '{"ips":["45.79.12.44","24.48.0.1","8.8.8.8"]}'
```

**Response**

```json
{
  "results": [
    { "ip": "45.79.12.44", "country": "US", "city": "Dallas",
      "asn": 63949, "asn_org": "Akamai Technologies, Inc.", "is_datacenter": false },
    { "ip": "24.48.0.1", "country": "CA", "region": "Quebec", "city": "Montreal",
      "asn": 5769, "asn_org": "Videotron Ltee", "is_datacenter": false },
    { "ip": "8.8.8.8", "country": "US", "asn": 15169,
      "asn_org": "Google LLC", "is_datacenter": true }
  ]
}
```

**Node.js**

```js
// Label a whole proxy list in ONE call. Repeats of the same host
// cost nothing, so there is no need to deduplicate first.
const ips = proxies.map((p) => p.split(":")[0]);

const res = await fetch("https://hproxy.com/api/ip", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ ips }), // up to 100 000
});

console.log("addresses charged:", res.headers.get("X-RateLimit-Cost"));
console.log("budget left:", res.headers.get("X-RateLimit-Remaining"));

const { results } = await res.json(); // same order as `ips`

// Bigger than 100 000? Send it in chunks of 100 000.
```

| Status | Meaning |
| --- | --- |
| `200` | Lookup succeeded. A result with "found": false means we have no data for that address, which is not an error. |
| `400 invalid_ip` | Not a valid IPv4 or IPv6 address. Single lookups only: inside a batch that line comes back as { "found": false, "code": "invalid_ip" } and the rest of the batch is unaffected. |
| `400 private_ip` | A private, loopback, link-local, CGNAT or otherwise reserved address. These have no public location. Inside a batch it behaves like invalid_ip above. |
| `400 batch_too_large` | More than 100 000 addresses in one batch. Split the list. |
| `429 rate_limited` | Too many addresses too quickly from your IP. Retry-After tells you how long. |
| `429 daily_quota` | Your IP has spent its daily address budget. It refills continuously, so a smaller batch fits sooner. |
| `429 global_rate_limited` | The free service as a whole is at capacity, not you specifically. Retry-After tells you how long. |
| `503 server_busy` | We are already resolving as many addresses as we can hold. Retry in a few seconds. |

> [!NOTE] **Location and network only.** This API answers where an address is and which network announces it. It deliberately does not return fraud scores, VPN, Tor or proxy detection, or abuse history. If you need those, they are a separate product, not part of the free tier.

> [!WARNING] **`is_datacenter` is best effort.** It reflects how the address's network is classified, and that classification is not perfect: some hosting ranges are recorded as residential and occasionally the reverse. Treat it as a hint, not a verdict. `asn` and `asn_org` are the reliable signal if you need to reason about who runs an address. Country and ASN are accurate; city is absent for anycast addresses rather than guessed.

> [!TIP] Building a proxy checker? Our own desktop checker is open source and uses exactly this endpoint to fill its location and ISP columns. Feel free to do the same.

> [!NOTE] **Use it from an AI assistant**: AI assistants can call this as the `ip_lookup` tool of HProxy's MCP server: add `https://mcp.hproxy.com/mcp` as a remote MCP server, nothing to install and no key. The line for each assistant (Claude, ChatGPT, Cursor, VS Code and more) is on [/tools/ai](https://hproxy.com/tools/ai), and the tools in full are in [the MCP server docs](https://hproxy.com/docs/free/mcp-server).

## MCP server for AI assistants

*HProxy's remote MCP server at https://mcp.hproxy.com/mcp: the free proxy list, the proxy checker and the IP lookup as tools in Claude, ChatGPT, Cursor and any MCP client. No key, nothing to install.*

URL: https://hproxy.com/docs/free/mcp-server

HProxy runs a remote MCP server at `https://mcp.hproxy.com/mcp`. It gives an AI assistant the free proxy list, the proxy checker and the IP lookup as three tools: `proxy_list`, `proxy_check` and `ip_lookup`. No key, no account, nothing to install. It is listed in the official MCP Registry as `com.hproxy/mcp`.

### Add the MCP server to your assistant

#### Claude Code

In a terminal:

```bash
claude mcp add --transport http hproxy https://mcp.hproxy.com/mcp
```

#### Claude and Claude Desktop

Settings, Connectors, Add custom connector, then paste the address:

```text
https://mcp.hproxy.com/mcp
```

#### ChatGPT

Settings, Security and login, turn on Developer mode, then create an app with this address and No authentication (Plus, Pro, Business, Enterprise and Education, on the web):

```text
https://mcp.hproxy.com/mcp
```

#### Cursor

In ~/.cursor/mcp.json:

```json
{ "mcpServers": { "hproxy": { "url": "https://mcp.hproxy.com/mcp" } } }
```

#### VS Code

In .vscode/mcp.json:

```json
{ "servers": { "hproxy": { "type": "http", "url": "https://mcp.hproxy.com/mcp" } } }
```

#### Windsurf

In ~/.codeium/windsurf/mcp_config.json:

```json
{ "mcpServers": { "hproxy": { "serverUrl": "https://mcp.hproxy.com/mcp" } } }
```

#### Gemini CLI

In ~/.gemini/settings.json:

```json
{ "mcpServers": { "hproxy": { "httpUrl": "https://mcp.hproxy.com/mcp" } } }
```

### The three MCP tools

*Tool*

| Field | Type | Description |
| --- | --- | --- |
| `proxy_list` | `country, protocol, anonymity, limit` | Live free proxies from the public pool. All arguments are optional: `country` (two letters), `protocol` (http, https, socks4, socks5), `anonymity` (elite, anonymous, transparent), `limit` (1 to 200, default 25). |
| `proxy_check` | `proxies` | A real live test of up to 25 proxies given as `ip:port`: alive, protocols, anonymity, latency and where each one exits. |
| `ip_lookup` | `ips` | Country, region, city, coordinates, timezone, ASN and network for up to 50 public addresses. |

### MCP server limits and errors

Each tool runs the same limits per IP address as the website's own endpoint for it. The list: 120 requests in a burst, then 2 a second. The checker: 120 requests in a burst, then 5 a second, and 300,000 proxies checked a day. The lookup: 900 requests in a burst, then 30 a second, and 2,000,000 addresses a day. A tool that cannot run answers with `isError` and a sentence; a limit says how many seconds to wait, so a model waits instead of calling again in a loop.

### Claude Code plugin and Gemini CLI extension

#### Claude Code plugin

The server plus a skill that tells Claude how to use it well. In a terminal:

```bash
claude plugin marketplace add hproxy-com/hproxy-mcp
claude plugin install hproxy@hproxy
```

#### Gemini CLI extension

The server plus a short guide for the model. In a terminal:

```bash
gemini extensions install https://github.com/hproxy-com/hproxy-mcp
```

The setup for every assistant is also on GitHub: [hproxy-com/hproxy-mcp](https://github.com/hproxy-com/hproxy-mcp).

### MCP protocol details

Streamable HTTP: one JSON-RPC message per POST and one JSON answer, with no session and no stream. Protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05. CORS is open for browser-based clients. A browser that opens the address is sent to [/tools/ai](https://hproxy.com/tools/ai).

### The same tools on your own computer

The `hproxy` command carries the same three tools as a local MCP server, started with `hproxy mcp`, plus tools that connect your computer through a proxy. One file for macOS, Linux and Windows, on x64 and ARM, Raspberry Pi included, built in public from the app's source: [the 0.3.8 release](https://github.com/hproxy-com/proxy-all-in-one-tool/releases/tag/cli-v0.3.8). Install it in one line.

#### macOS and Linux

```bash
curl -fsSL https://hproxy.com/install.sh | sh
```

#### Windows, in PowerShell

```powershell
irm https://hproxy.com/install.ps1 | iex
```

Then `claude mcp add hproxy -- hproxy mcp` in Claude Code, or `hproxy list`, `hproxy check` and `hproxy ip` straight from the terminal. The [HProxy app](https://hproxy.com/proxy-checker) carries it too (Windows, macOS and Linux).