HProxy Proxy checker API

openapi: 3.2.0
info:
  title: HProxy Proxy checker API
  version: 1.0.0
  description: 'Buy and manage proxies from a prepaid wallet, run the Scraper API, or use the free no-key APIs: a live proxy list, a proxy checker and an IP lookup. JSON in, JSON out. Money is always integer cents (120 = $1.20), never floats.'
  contact:
    url: https://hproxy.com/contact
  license:
    name: Proprietary
servers:
- url: https://hproxy.com
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Proxy checker API
paths:
  /api/proxy-check:
    get:
      operationId: free-proxy-check
      summary: Check one proxy
      description: '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, 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.'
      tags:
      - Proxy checker API
      parameters:
      - name: proxy
        in: query
        required: true
        description: The proxy to test, e.g. 203.0.113.7:1080, or host:port:user:pass for one with a login.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                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
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security: []
    post:
      operationId: free-proxy-check-batch
      summary: Check up to 1,000 at once
      description: '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.'
      tags:
      - Proxy checker API
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                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
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                proxies:
                  type: array
                  items: {}
                  description: Up to 1,000 proxy lines per request (ip:port, host:port:user:pass or user:pass@host:port).
              required:
              - proxies
  /api/free-proxy/check:
    post:
      operationId: free-proxy-check-stream
      summary: Stream a big list, up to 100,000
      description: 'The endpoint behind our online proxy checker 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 instead: nothing stays connected, and an interrupted job resumes by itself.'
      tags:
      - Proxy checker API
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                proxies:
                  type: array
                  items: {}
                  description: Up to 100,000 proxy lines.
                timeout_ms:
                  type: integer
                  description: Per-probe budget, 1,000 to 60,000. Default 8,000.
                retries:
                  type: integer
                  description: Extra attempts for a proxy that does not answer, 0 to 3. Default 0.
                protocols:
                  type: array
                  items: {}
                  description: Any of http, https, socks4, socks5. Default all four.
                measure_speed:
                  type: boolean
                  description: Also measure download speed through each working proxy (speed_mbps).
                measure_udp:
                  type: boolean
                  description: Also test whether each working SOCKS5 proxy relays UDP (supports_udp).
              required:
              - proxies
  /api/v1/free-proxy/check:
    post:
      operationId: free-proxy-check-keyed
      summary: With your API key
      description: '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" }`.'
      tags:
      - Proxy checker API
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                X-API-Key:
                  type: string
                  description: 'Your hpx_ key (or Authorization: Bearer hpx_...).'
              required:
              - X-API-Key
  /api/v1/proxy-check/jobs:
    post:
      operationId: check-jobs-create
      summary: Hand over a big list as a job
      description: '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.'
      tags:
      - Proxy checker API
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                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
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                X-API-Key:
                  type: string
                  description: 'Your hpx_ key (or Authorization: Bearer hpx_...).'
                proxies:
                  type: array
                  items: {}
                  description: Up to 100,000 proxy lines. A text/plain body of one line per proxy works too.
                label:
                  type: string
                  description: Your own name for the run, up to 64 characters. Shown in the dashboard.
                timeout_ms:
                  type: integer
                  description: Per-probe budget, 1,000 to 60,000. Default 8,000.
                retries:
                  type: integer
                  description: Extra attempts for a proxy that does not answer, 0 to 3. Default 0.
                protocols:
                  type: array
                  items: {}
                  description: Any of http, https, socks4, socks5. Default all four.
                measure_speed:
                  type: boolean
                  description: Also measure download speed through each working proxy (speed_mbps).
                measure_udp:
                  type: boolean
                  description: Also test whether each working SOCKS5 proxy relays UDP (supports_udp).
              required:
              - X-API-Key
              - proxies
  /api/v1/proxy-check/jobs/{id}:
    get:
      operationId: check-jobs-get
      summary: Watch a job
      description: '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": [ ... ] }`.'
      tags:
      - Proxy checker API
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: query
        required: true
        description: Your hpx_ key.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                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
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
    delete:
      operationId: check-jobs-cancel
      summary: Cancel a job
      description: 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.
      tags:
      - Proxy checker API
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: query
        required: true
        description: Your hpx_ key.
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
  /api/v1/proxy-check/jobs/{id}/results:
    get:
      operationId: check-jobs-results
      summary: Download the results
      description: '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`.'
      tags:
      - Proxy checker API
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: X-API-Key
        in: query
        required: true
        description: Your hpx_ key.
        schema:
          type: string
      - name: format
        in: query
        required: false
        description: Default ndjson. txt is the working proxies only; csv carries a header row.
        schema:
          type: string
      - name: only
        in: query
        required: false
        description: Drop the dead rows (txt does this anyway).
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Invalid input. The body names the field and the accepted set.
        '401':
          description: Missing or invalid API key.
        '429':
          description: Rate limited. Retry after the delay in the response.
      security:
      - ApiKeyAuth: []
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your API key. Free keyless endpoints ignore it.
x-endpoint-count: 163
x-generated-from: https://hproxy.com/docs
x-llms: https://hproxy.com/llms-full.txt