Plans & line generation

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. 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.

A single active plan you own: the per-customer read for a reseller dashboard. 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.

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.

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.

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.

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.

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.

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 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.