# HProxy Documentation > Two APIs from HProxy: a free, no-key proxy list + checker API, and the Scrapers API (117 endpoints across 23+ platforms returning clean JSON). This file is the complete documentation as a single page. Source: https://hproxy.com/docs --- # Getting started ## HProxy Documentation *Two APIs from HProxy: a free, no-key proxy list API you can call right now, and the Scrapers API — 117 endpoints across 23+ platforms returning clean, structured JSON.* URL: https://hproxy.com/docs Two APIs. A **free, no-key proxy list API** you can call right now, and the **Scrapers API** — 117 endpoints across 23+ platforms. Clean JSON, predictable shapes, no parsers to maintain. - [Quickstart](https://hproxy.com/docs/quickstart) — Three steps to your first scraper call. - [Authentication](https://hproxy.com/docs/authentication) — Get an API key and pass it on every request. - [Playground](https://hproxy.com/docs/playground) — Pick an endpoint, hit Run, see a real response. - [Free proxy list API](https://hproxy.com/docs/free-proxy-api) — A free, no-auth proxy list as JSON, CSV or text. - [Proxy checker API](https://hproxy.com/docs/proxy-checker-api) — Test if a proxy is alive, fast and free. - [Endpoint reference](https://hproxy.com/docs/endpoints) — Every endpoint across every platform. ### What you get The **Scrapers API** turns any supported page into structured data with one REST call — you send a small JSON body, you get parsed JSON back in a predictable envelope, plus the exact cost of the call. No headless browsers, no proxies to rotate, no selectors to maintain when a site changes its markup. The **free tools** — the [proxy list API](https://hproxy.com/docs/free-proxy-api) and the [proxy checker API](https://hproxy.com/docs/proxy-checker-api) — need no key and no signup. Call them straight from a browser, a script, or CI. > [!TIP] **Built for AI** — Using an AI assistant? Grab the entire documentation as one markdown page at [/llms-full.txt](https://hproxy.com/llms-full.txt), or hit **Copy for AI** in the top bar, and paste it into Claude. ## Quickstart *Three steps to your first Scrapers API call: get a key, call an endpoint, get clean JSON.* URL: https://hproxy.com/docs/quickstart Three steps to your first call. 1. **Get a key** — Generate one in your [dashboard](https://hproxy.com/dashboard/scrapers). Keys look like `hpx_…` and authenticate every request. 2. **Call an endpoint** — `POST` to `/v1/scrape/{platform}/{action}` with a small JSON body. `GET` with query params works too. 3. **Get clean JSON** — Parsed, structured data in a predictable envelope. Plus the run id and the exact cost of the call. ### Your first call Here's a complete example against the Instagram Profile endpoint — cURL, Node.js and Python: **cURL** ```bash curl https://hproxy.com/v1/scrape/instagram/profile \ -H "Authorization: Bearer $HPROXY_KEY" \ -H "Content-Type: application/json" \ -d '{"handle":"levelsio"}' ``` **Node.js** ```js const res = await fetch("https://hproxy.com/v1/scrape/instagram/profile", { method: "POST", headers: { Authorization: `Bearer ${process.env.HPROXY_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "handle": "levelsio" }), }); const { data } = await res.json(); console.log(data); ``` **Python** ```python import os, requests res = requests.post( "https://hproxy.com/v1/scrape/instagram/profile", headers={"Authorization": f"Bearer {os.environ['HPROXY_KEY']}"}, json={"handle":"levelsio"}, ) print(res.json()["data"]) ``` **Response** ```json { "platform": "instagram", "scraper": "instagram-profile-collect-by-handle", "input": { "handle": "levelsio" }, "data": { "data": { "user": { "biography": "Explore the universe and discover our home planet with @NASA, the official NASA Instagram account.", "external_url": "https://www.nasa.gov", "edge_followed_by": { "count": 96500000 }, "edge_follow": { "count": 78 }, "full_name": "NASA", "id": "528817151", "is_business_account": true, "is_verified": true, "profile_pic_url_hd": "https://scontent-lga3-1.cdninstagram.com/v/t51.2885-19/280722101_412901447453676_….jpg", "username": "nasa", "edge_owner_to_timeline_media": { "count": 4218, "edges": [ { "node": { "__typename": "GraphVideo", "id": "3622533050035914969", "shortcode": "DJF0p2ygMjZ", "display_url": "https://scontent-lga3-1.cdninstagram.com/v/t51.2885-15/491901123_….jpg", "edge_media_to_caption": { "edges": [] }, "edge_media_to_comment": { "count": 1428 }, "taken_at_timestamp": 1746059630, "edge_liked_by": { "count": 412705 } } } ] } } } }, "records": 1, "costUsd": 0.01, "requestId": "run_3Qm8x2V7nKp4dWcF", "elapsedMs": 1840 } ``` > [!NOTE] Failed scrapes (a 4xx/5xx from the source site) are **never billed**. You only pay for a successful, parsed result. Minimum $0.01 per call. - [Authentication](https://hproxy.com/docs/authentication) — How to pass your key and keep it safe. - [The response envelope](https://hproxy.com/docs/response-envelope) — The shape every successful call returns. ## Authentication *Every Scrapers API request authenticates with an API key. Send it as X-API-Key or Authorization: Bearer.* URL: https://hproxy.com/docs/authentication Every request authenticates with an API key. Generate one in your [dashboard](https://hproxy.com/dashboard/scrapers). Keys look like `hpx_…`. Send it as either header — both are accepted, same as Stripe / OpenAI: ```http X-API-Key: hpx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # or Authorization: Bearer hpx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` > [!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](https://hproxy.com/dashboard/settings/api-keys). --- # Scrapers API ## Playground *Pick an endpoint and hit Run to see a real response shape. Uses sample data — it won't touch your balance.* URL: https://hproxy.com/docs/playground Pick an endpoint and hit **Run** to see a real response shape. This demo uses sample data, so it won't touch your balance. An interactive playground is available at https://hproxy.com/docs/playground — pick an endpoint and run it against sample data (no balance used). ## The response envelope *Every successful Scrapers API call returns the same top-level shape: scraped data under `data`, plus metadata about the call.* URL: https://hproxy.com/docs/response-envelope Every successful call returns the same top-level shape. The scraped data lives under `data`; everything else is metadata about the call. | Field | Type | Description | | --- | --- | --- | | `platform` | `string` | The platform you called (e.g. instagram). | | `scraper` | `string` | The endpoint id that ran. | | `input` | `object` | The parameters you sent, echoed back. | | `data` | `object` | The scraped result. Clean, structured JSON. | | `records` | `number` | How many records the response contains. | | `costUsd` | `number` | What this call cost, in USD (min $0.01). | | `requestId` | `string` | Run id. Reference it in support / the dashboard. | | `elapsedMs` | `number` | How long the call took upstream. | ## Status codes *Standard HTTP semantics for the Scrapers API. Failed scrapes (4xx/5xx from the source) are never billed.* URL: https://hproxy.com/docs/status-codes Standard HTTP semantics. Failed scrapes (4xx/5xx from the source) are **never billed**. | Status | Meaning | | --- | --- | | `200` | Success. Data in the envelope. | | `400` | Invalid input. Check the parameters. | | `401` | Missing or invalid API key. | | `402` | Insufficient balance. Top up your wallet. | | `404` | Unknown endpoint. | | `429` | Rate limited. Back off and retry (Retry-After header). | | `502` | Upstream error. Retry shortly. Not billed. | ### Good to know > [!NOTE] **Idempotency:** send an `X-Request-Id` header and retries return the original result without re-charging. > [!NOTE] **Pay per success:** one call, one charge. Never multiplied by record count. Minimum $0.01 per call. > [!NOTE] **Auth:** send `X-API-Key` or `Authorization: Bearer`. Both work. ## Every endpoint *All 117 scrapers across 23+ platforms. Search by platform, name, or path.* URL: https://hproxy.com/docs/endpoints All 117 scrapers across 23+ platforms. Search by platform or name. | Platform | Endpoint | Path | Price | | --- | --- | --- | --- | | Instagram | Instagram Profile | `POST /v1/scrape/instagram/profile` | $0.0030 | | Instagram | Instagram Basic Profile | `POST /v1/scrape/instagram/basic-profile` | $0.0030 | | Instagram | Instagram Post | `POST /v1/scrape/instagram/post` | $0.0330 | | Instagram | Instagram User Posts | `POST /v1/scrape/instagram/posts` | $0.0030 | | Instagram | Instagram User Reels | `POST /v1/scrape/instagram/reels` | $0.0030 | | Instagram | Instagram Media Transcript | `POST /v1/scrape/instagram/transcript` | $0.0300 | | Instagram | Instagram Reels Search | `POST /v1/scrape/instagram/reels-search` | $0.0050 | | Instagram | Instagram Post Comments | `POST /v1/scrape/instagram/comments` | $0.0030 | | Instagram | Instagram User Highlights | `POST /v1/scrape/instagram/highlights` | $0.0030 | | Instagram | Instagram Highlight Detail | `POST /v1/scrape/instagram/highlight` | $0.0030 | | Instagram | Instagram Profile Embed HTML | `POST /v1/scrape/instagram/embed` | $0.0030 | | TikTok | TikTok Profile | `POST /v1/scrape/tiktok/profile` | $0.0030 | | TikTok | TikTok Profile Region | `POST /v1/scrape/tiktok/profile-region` | $0.0030 | | TikTok | TikTok User Audience Demographics | `POST /v1/scrape/tiktok/audience` | $0.0780 | | TikTok | TikTok Video | `POST /v1/scrape/tiktok/video` | $0.0330 | | TikTok | TikTok Video Transcript | `POST /v1/scrape/tiktok/video-transcript` | $0.0330 | | TikTok | TikTok Profile Videos | `POST /v1/scrape/tiktok/profile-videos` | $0.0030 | | TikTok | TikTok Live Status | `POST /v1/scrape/tiktok/live-status` | $0.0030 | | TikTok | TikTok Video Comments | `POST /v1/scrape/tiktok/video-comments` | $0.0030 | | TikTok | TikTok Comment Replies | `POST /v1/scrape/tiktok/comment-replies` | $0.0030 | | TikTok | TikTok User Following | `POST /v1/scrape/tiktok/following` | $0.0030 | | TikTok | TikTok User Followers | `POST /v1/scrape/tiktok/followers` | $0.0030 | | TikTok | TikTok Search Users | `POST /v1/scrape/tiktok/search-users` | $0.0030 | | TikTok | TikTok Hashtag Search | `POST /v1/scrape/tiktok/search-hashtag` | $0.0030 | | TikTok | TikTok Keyword Search | `POST /v1/scrape/tiktok/search` | $0.0030 | | TikTok | TikTok Popular Creators | `POST /v1/scrape/tiktok/popular-creators` | $0.0050 | | TikTok | TikTok Popular Hashtags | `POST /v1/scrape/tiktok/popular-hashtags` | $0.0030 | | TikTok | TikTok Song Details | `POST /v1/scrape/tiktok/song` | $0.0030 | | TikTok | TikTok Song Videos | `POST /v1/scrape/tiktok/song-videos` | $0.0030 | | TikTok | TikTok Trending Feed | `POST /v1/scrape/tiktok/trending` | $0.0030 | | TikTok | TikTok Shop Search | `POST /v1/scrape/tiktok/shop-search` | $0.0030 | | TikTok | TikTok Shop Products | `POST /v1/scrape/tiktok/shop-products` | $0.0030 | | TikTok | TikTok Shop Product Details | `POST /v1/scrape/tiktok/shop-product` | $0.0050 | | TikTok | TikTok Shop Product Reviews | `POST /v1/scrape/tiktok/shop-product-reviews` | $0.0030 | | LinkedIn | LinkedIn Profile | `POST /v1/scrape/linkedin/profile` | $0.0050 | | LinkedIn | LinkedIn Company | `POST /v1/scrape/linkedin/company` | $0.0050 | | LinkedIn | LinkedIn Company Posts | `POST /v1/scrape/linkedin/company-posts` | $0.0050 | | LinkedIn | LinkedIn Post | `POST /v1/scrape/linkedin/post` | $0.0050 | | YouTube | YouTube Channel | `POST /v1/scrape/youtube/channel` | $0.0030 | | YouTube | YouTube Channel Videos | `POST /v1/scrape/youtube/channel-videos` | $0.0030 | | YouTube | YouTube Channel Shorts | `POST /v1/scrape/youtube/channel-shorts` | $0.0030 | | YouTube | YouTube Video | `POST /v1/scrape/youtube/video` | $0.0030 | | YouTube | YouTube Video Transcript | `POST /v1/scrape/youtube/transcript` | $0.0300 | | YouTube | YouTube Search | `POST /v1/scrape/youtube/search` | $0.0030 | | YouTube | YouTube Video Comments | `POST /v1/scrape/youtube/comments` | $0.0030 | | YouTube | YouTube Trending Shorts | `POST /v1/scrape/youtube/trending-shorts` | $0.0030 | | Google | Google Search Results | `POST /v1/scrape/google/search` | $0.0050 | | Twitter / X | Twitter / X Profile | `POST /v1/scrape/twitter/profile` | $0.0030 | | Twitter / X | Twitter / X User Tweets | `POST /v1/scrape/twitter/tweets` | $0.0030 | | Twitter / X | Twitter / X Tweet | `POST /v1/scrape/twitter/tweet` | $0.0030 | | Twitter / X | Twitter / X Tweet Transcript | `POST /v1/scrape/twitter/tweet-transcript` | $0.0300 | | Facebook | Facebook Profile | `POST /v1/scrape/facebook/profile` | $0.0030 | | Facebook | Facebook Profile Reels | `POST /v1/scrape/facebook/profile-reels` | $0.0030 | | Facebook | Facebook Profile Photos | `POST /v1/scrape/facebook/profile-photos` | $0.0030 | | Facebook | Facebook Profile Posts | `POST /v1/scrape/facebook/profile-posts` | $0.0030 | | Facebook | Facebook Profile Events | `POST /v1/scrape/facebook/profile-events` | $0.0030 | | Facebook | Facebook Post | `POST /v1/scrape/facebook/post` | $0.0030 | | Facebook | Facebook Post Transcript | `POST /v1/scrape/facebook/post-transcript` | $0.0300 | | Facebook | Facebook Post Comments | `POST /v1/scrape/facebook/post-comments` | $0.0030 | | Facebook | Facebook Comment Replies | `POST /v1/scrape/facebook/comment-replies` | $0.0030 | | Facebook | Facebook Group Posts | `POST /v1/scrape/facebook/group-posts` | $0.0030 | | Facebook | Facebook Events Search | `POST /v1/scrape/facebook/events-search` | $0.0030 | | Facebook | Facebook Events by City | `POST /v1/scrape/facebook/events` | $0.0030 | | Facebook | Facebook Event Details | `POST /v1/scrape/facebook/event` | $0.0030 | | Facebook | Facebook Ad Library Detail | `POST /v1/scrape/facebook/ad` | $0.0050 | | Facebook | Facebook Ad Library Search | `POST /v1/scrape/facebook/ad-search` | $0.0050 | | Facebook | Facebook Company Ads | `POST /v1/scrape/facebook/ad-company` | $0.0050 | | Facebook | Facebook Ad Library Company Search | `POST /v1/scrape/facebook/ad-companies-search` | $0.0030 | | Google | Google Ad Library Company Ads | `POST /v1/scrape/google/ad-company` | $0.0780 | | Google | Google Ad Detail | `POST /v1/scrape/google/ad` | $0.0050 | | Google | Google Advertiser Search | `POST /v1/scrape/google/advertiser-search` | $0.0030 | | LinkedIn | LinkedIn Ad Library Search | `POST /v1/scrape/linkedin/ad-search` | $0.0050 | | LinkedIn | LinkedIn Ad Detail | `POST /v1/scrape/linkedin/ad` | $0.0050 | | Reddit | Reddit Subreddit Details | `POST /v1/scrape/reddit/subreddit` | $0.0030 | | Reddit | Reddit Subreddit Posts | `POST /v1/scrape/reddit/subreddit-posts` | $0.0030 | | Reddit | Reddit Post Comments | `POST /v1/scrape/reddit/comments` | $0.0030 | | Reddit | Reddit Search | `POST /v1/scrape/reddit/search` | $0.0030 | | Reddit | Reddit Subreddit Search | `POST /v1/scrape/reddit/subreddit-search` | $0.0030 | | Threads | Threads Profile | `POST /v1/scrape/threads/profile` | $0.0030 | | Threads | Threads User Posts | `POST /v1/scrape/threads/posts` | $0.0030 | | Threads | Threads Post | `POST /v1/scrape/threads/post` | $0.0030 | | Threads | Threads Search | `POST /v1/scrape/threads/search` | $0.0030 | | Bluesky | Bluesky Profile | `POST /v1/scrape/bluesky/profile` | $0.0030 | | Bluesky | Bluesky User Posts | `POST /v1/scrape/bluesky/posts` | $0.0030 | | Bluesky | Bluesky Post | `POST /v1/scrape/bluesky/post` | $0.0030 | | Truth Social | Truth Social Profile | `POST /v1/scrape/truth-social/profile` | $0.0030 | | Truth Social | Truth Social User Posts | `POST /v1/scrape/truth-social/posts` | $0.0030 | | Truth Social | Truth Social Post | `POST /v1/scrape/truth-social/post` | $0.0030 | | Pinterest | Pinterest Search | `POST /v1/scrape/pinterest/search` | $0.0030 | | Pinterest | Pinterest Pin | `POST /v1/scrape/pinterest/pin` | $0.0030 | | Pinterest | Pinterest User Boards | `POST /v1/scrape/pinterest/boards` | $0.0030 | | Pinterest | Pinterest Board Pins | `POST /v1/scrape/pinterest/board` | $0.0030 | | Twitch | Twitch Profile | `POST /v1/scrape/twitch/profile` | $0.0030 | | Twitch | Twitch User Videos | `POST /v1/scrape/twitch/videos` | $0.0030 | | Twitch | Twitch Clip | `POST /v1/scrape/twitch/clip` | $0.0030 | | Snapchat | Snapchat Profile | `POST /v1/scrape/snapchat/profile` | $0.0030 | | Spotify | Spotify Artist | `POST /v1/scrape/spotify/artist` | $0.0030 | | Spotify | Spotify Track | `POST /v1/scrape/spotify/track` | $0.0030 | | Spotify | Spotify Album | `POST /v1/scrape/spotify/album` | $0.0030 | | SoundCloud | SoundCloud Artist | `POST /v1/scrape/soundcloud/artist` | $0.0030 | | Kick | Kick Clip | `POST /v1/scrape/kick/clip` | $0.0030 | | Linktree | Linktree Page | `POST /v1/scrape/linktree/page` | $0.0030 | | Komi | Komi Page | `POST /v1/scrape/komi/page` | $0.0030 | | Pillar | Pillar Page | `POST /v1/scrape/pillar/page` | $0.0030 | | Lnk.Bio | Linkbio Page | `POST /v1/scrape/linkbio/page` | $0.0030 | | Linkme | Linkme Profile | `POST /v1/scrape/linkme/page` | $0.0030 | | Amazon | Amazon Shop Page | `POST /v1/scrape/amazon/shop` | $0.0030 | | TikTok | TikTok Top Search | `POST /v1/scrape/tiktok/search-top` | $0.0030 | | TikTok | TikTok Shop User Showcase | `POST /v1/scrape/tiktok/shop-showcase` | $0.0030 | | YouTube | YouTube Hashtag Search | `POST /v1/scrape/youtube/search-hashtag` | $0.0030 | | YouTube | YouTube Comment Replies | `POST /v1/scrape/youtube/comment-replies` | $0.0030 | | YouTube | YouTube Playlist | `POST /v1/scrape/youtube/playlist` | $0.0030 | | YouTube | YouTube Community Post | `POST /v1/scrape/youtube/community-post` | $0.0030 | | Twitter / X | Twitter / X Community | `POST /v1/scrape/twitter/community` | $0.0030 | | Twitter / X | Twitter / X Community Tweets | `POST /v1/scrape/twitter/community-tweets` | $0.0030 | | Threads | Threads Search Users | `POST /v1/scrape/threads/search-users` | $0.0030 | | Twitch | Twitch User Schedule | `POST /v1/scrape/twitch/schedule` | $0.0030 | --- # Free tools ## Free proxy list API *A free, no-auth endpoint returning HProxy's continuously-verified public proxy list as JSON, CSV or text, filterable by country, protocol and anonymity.* URL: https://hproxy.com/docs/free-proxy-api A free, no-auth endpoint that returns our continuously-verified public proxy list as JSON, CSV or plain text. Filter by country, protocol and anonymity. CORS-enabled, so you can call it straight from a browser too. **Live SOCKS5 proxies in the US, as JSON** ```bash curl "https://hproxy.com/api/proxy-list?format=json&country=US&protocol=socks5" ``` **Response · array of proxies** ```json [ { "ip": "203.0.113.7", "port": 1080, "protocols": ["socks4", "socks5"], "country_code": "US", "city": "New York", "anonymity": "elite", "latency_ms": 142, "uptime_pct": 71.4, "status": "alive", "last_alive_at": "2026-06-17T00:00:00Z" } ] ``` ### Query parameters All optional, combine them freely. Base URL: `https://hproxy.com/api/proxy-list`. | Field | Type | Description | | --- | --- | --- | | `format` | `txt | json | csv` | Output format. Default txt (ip:port per line). | | `country` | `ISO code` | Only proxies exiting this country, e.g. US, DE, GB. | | `protocol` | `http | https | socks4 | socks5` | Only this protocol. Comma-separate for several. | | `anonymity` | `elite | anonymous | transparent` | Only this anonymity grade. | | `limit` | `1 - 10000` | Maximum proxies to return. Default 10000. | | `recent` | `true` | Include proxies alive within the last 72h, not only live right now. | ### Good to know > [!NOTE] **No key, no signup.** Free and unauthenticated, but rate limited to roughly 60 requests per minute per IP (a clean `429` with a `Retry-After` header if you exceed it). Responses are cached ~60s, so you rarely need to poll fast. > [!NOTE] **Three formats.** `txt` (ip:port lines), `json` (array), `csv`. An `X-Total-Count` header gives the row count. > [!NOTE] **Also on GitHub.** Static hourly snapshots (txt/json/csv, by country) at [github.com/hproxy-com/free-proxy-list](https://github.com/hproxy-com/free-proxy-list). > [!TIP] **Need proxies that don't die?** — Free proxies are shared and unstable. HProxy residential, ISP and mobile proxies stay up, from $0.99/GB. [See plans →](https://hproxy.com/residential) ## Proxy checker API *Check whether a proxy is alive and get its latency, protocols, anonymity and location. Free, no key. Each request runs a real live test.* URL: https://hproxy.com/docs/proxy-checker-api Check whether a proxy is alive and get its latency, protocols, anonymity and location. Free, no key. Each request runs a real live test against the proxy, so it is rate limited more tightly than the list. **Check one proxy** ```bash curl "https://hproxy.com/api/proxy-check?proxy=1.2.3.4:8080" ``` **Response** ```json { "input": "1.2.3.4:8080", "ip": "1.2.3.4", "port": 8080, "alive": true, "protocols": ["http"], "anonymity": "elite", "latency_ms": 184, "country_code": "US", "city": "New York", "asn_org": "Example ISP", "error": null } ``` ### Check several at once POST up to 25 proxies. The response is `{ "count": n, "results": [ ... ] }` with the same per-proxy shape. ```bash curl -X POST https://hproxy.com/api/proxy-check \ -H "Content-Type: application/json" \ -d '{"proxies": ["1.2.3.4:8080", "5.6.7.8:1080"]}' ``` ### Good to know > [!NOTE] **No key.** Rate limited to ~12 requests/min per IP, up to 25 proxies per POST. Over that returns a `429` with `Retry-After`. > [!NOTE] **Real live test.** Each proxy is actually connected to, so a dead one can take a few seconds to report. > [!NOTE] **Your proxies stay yours.** The checker tests the proxies you paste and returns the results. They are never saved or added to our [free list](https://hproxy.com/free-proxy-list).