Plans & line generation

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

GEThproxy.com/api/v1/planskey

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

List plans

Your active plans: residential GB balances and dedicated allocations. The id is what you pass to the endpoints below; label is your own tag (see PATCH), null until you set it.

GEThproxy.com/api/v1/plans/{id}key

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

Get one plan

A single active plan you own: the per-customer read for a reseller dashboard: remaining GB (refreshed from live usage about every 30 minutes), expiry and your label.

PATCHhproxy.com/api/v1/plans/{id}key

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"}'

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 payloads, so every signal is already attributed to your customer. null (or an empty body) clears it.

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

POSThproxy.com/api/v1/plans/{id}/generatekey

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}'

Generate proxy lines

Turn a residential plan you own into ready-to-use proxy lines, fully programmatic, using the same hardened generator the dashboard uses. Lines come back as host:port:username:password with the targeting baked into the username, so any HTTP or SOCKS5 client uses them as-is. 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.

Parameter	Type	Required	Description
`protocol`	string	optional	"http" (default) or "socks5".
`count`	integer	optional	Lines to return, 1 to 1000. Default 1.
`country`	string	optional	Country targeting, e.g. "US" (letters only, 2 to 40 chars).
`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. Residential Survey plans only (400 on other products).
`stickyMinutes`	integer	optional	Turns sticky on. Omit for rotating IPs. On Residential Premium and Plus the number is the session length in minutes. 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.

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	How to ask	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} or be pushed plan.low_traffic at 10%.

Building a reseller integration? The reselling guide walks the whole loop, and the Reseller API does the same generation as each of your customers so every line is billed and isolated per customer.

← Previous

Orders

Your proxies

Need a hand wiring this up? Email support@hproxy.com. A real person reads every message.