HProxy Plans & line generation API

openapi: 3.2.0
info:
  title: HProxy Plans & line generation 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: Plans & line generation
paths:
  /api/v1/plans:
    get:
      operationId: plans
      summary: List plans
      description: '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.'
      tags:
      - Plans & line generation
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                plans:
                - id: cmjfmhhpd004c4i4hqsk3mzrr
                  product: residential-premium
                  productId: residential-premium
                  status: active
                  dataGbTotal: 1
                  dataGbRemaining: 1
                  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
                  dataGbRemaining: 0
                  expiresAt: null
                  createdAt: '2026-03-02T09:14:22.104Z'
                  label: customer-2077
        '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/plans/{id}:
    get:
      operationId: plan-get
      summary: Get one plan
      description: '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.'
      tags:
      - Plans & line generation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                id: cmjfmhhpd004c4i4hqsk3mzrr
                product: residential-premium
                productId: residential-premium
                status: active
                dataGbTotal: 10
                dataGbRemaining: 3.2
                expiresAt: null
                createdAt: '2026-07-23T01:07:14.785Z'
                label: customer-1042
        '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: []
    patch:
      operationId: plan-label
      summary: Label a plan
      description: '`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 payloads, so every signal is already attributed to your customer. `null` (or an empty body) clears it.'
      tags:
      - Plans & line generation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                id: cmjfmhhpd004c4i4hqsk3mzrr
                product: residential-premium
                productId: residential-premium
                dataGbTotal: 10
                dataGbRemaining: 10
                expiresAt: null
                createdAt: '2026-07-23T01:07:14.785Z'
                label: customer-1042
        '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: false
        content:
          application/json:
            schema:
              type: object
              properties:
                label:
                  type: string
                  description: 1 to 64 characters, no control characters. null/omitted clears.
  /api/v1/plans/{id}/stats:
    get:
      operationId: plan-stats
      summary: Traffic statistics
      description: '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.'
      tags:
      - Plans & line generation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: days
        in: query
        required: false
        description: Window ending now, 1 to 30. Default 7.
        schema:
          type: integer
      - name: granularity
        in: query
        required: false
        description: '"hour" (windows up to 29 days) or "day". Default: hour up to 2 days, else day.'
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                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
                  requests: 15
                  successfulRequests: 15
                  successRate: 100
        '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/plans/{id}/whitelist:
    get:
      operationId: plan-whitelist
      summary: IP whitelist
      description: '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.'
      tags:
      - Plans & line generation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: ips
        in: query
        required: true
        description: 'POST / DELETE body: IP strings, or `{ip, description}` objects (description up to 80 characters).'
        schema:
          type: array
          items: {}
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                planId: cmjfmhhpd004c4i4hqsk3mzrr
                max: 150
                ips:
                - ip: 203.0.113.9
                  description: office
        '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/plans/{id}/sessions:
    get:
      operationId: plan-sessions
      summary: Sticky sessions
      description: '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.'
      tags:
      - Plans & line generation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        description: 'List only: the page to read, from 1. Default 1.'
        schema:
          type: integer
      - name: pageSize
        in: query
        required: false
        description: 'List only: sessions per page, 1 to 250. Default 250.'
        schema:
          type: integer
      - name: sessions
        in: query
        required: false
        description: 'Release only: 1 to 1,000 `{port, sessionId}` pairs, as the list shows them. Exactly those sessions end.'
        schema:
          type: array
          items: {}
      - name: ports
        in: query
        required: false
        description: 'Release only: 1 to 200 sticky ports. Every open session on them ends.'
        schema:
          type: integer
      - name: all
        in: query
        required: false
        description: 'Release only: `true` ends every open session on the plan.'
        schema:
          type: boolean
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                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'
        '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/plans/{id}/password:
    post:
      operationId: plan-password
      summary: Rotate the proxy password
      description: 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.
      tags:
      - Plans & line generation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                ok: true
                username: hproxy_k2m9x4qp7wz1
                password: 3f1c2a9e-8b7d-4e6f-a1b2-c3d4e5f60718
        '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/plans/{id}/generate:
    post:
      operationId: generate
      summary: Generate proxy lines
      description: '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 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 instead.'
      tags:
      - Plans & line generation
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
              example:
                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
        '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: false
        content:
          application/json:
            schema:
              type: object
              properties:
                protocol:
                  type: string
                  description: '"http" (default) or "socks5".'
                count:
                  type: integer
                  description: '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:
                  type: string
                  description: '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:
                  type: string
                  description: State / region targeting, where the pool supports it.
                city:
                  type: string
                  description: City targeting, where the pool supports it.
                isp:
                  type: string
                  description: ISP targeting by name. Residential Plus plans only (400 on other products).
                asn:
                  type: integer
                  description: 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:
                  type: string
                  description: '"windows", "android", "ios" or "mac": the device the exit IP belongs to. Residential Premium only.'
                strict:
                  type: boolean
                  description: '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:
                  type: integer
                  description: Up to 20 AS numbers to avoid. Not together with `excludeCountries`. Residential Premium only.
                excludeCountries:
                  type: array
                  items: {}
                  description: '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:
                  type: array
                  items: {}
                  description: Up to 20 state / region names to avoid inside `country` (e.g. ["California", "Texas"]); not together with a `state` target. Residential Premium only.
                excludeCities:
                  type: array
                  items: {}
                  description: Up to 20 city names to avoid inside `country` (e.g. ["New York", "Houston"]); not together with a `city` target. Residential Premium only.
                udp:
                  type: boolean
                  description: '`true` lets a `socks5` line open UDP relays (SOCKS5 UDP ASSOCIATE). Refused on `http`. Residential Premium only.'
                stickyMinutes:
                  type: integer
                  description: 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`.
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