Customer Plan API

The Customer Plan API is the proxy API for a single ColdProxy service: it lets you manage that one plan end to end in code rather than through the dashboard. With it you can generate proxy lists, read the available geo targets, manage your IP-authentication allow-list, rotate the password, check usage, manage SuperPort and blacklist rules, and run service actions like reboot, renew, or a speed upgrade. It is a per-service API: the key and settings belong to one plan, scoped to that plan's product type and configuration. If you provision and bill ColdProxy services in volume on behalf of your own customers, use the Reseller API instead; this page covers managing a plan you already own.

#Where to find it

Each plan exposes its own API on its settings page in the ColdProxy client area. Open the service you want to automate and you will find its API page, which shows the ready-to-use base URL (with your service id and key already filled in) plus a per-product command builder. The available commands depend on the product type: for example, bandwidth and usage commands appear on the Residential IPv4 (GB Based) plan, speed-tier commands on the speed-based plans, and geo commands only when geo-targeting is enabled for the service.

#Request format

Every call is an HTTP GET to the per-service endpoint, with three required query parameters and the action in a:

GET https://members.coldproxy.com/newsysapi.php?id={SERVICE_ID}&key={API_KEY}&a={action}

Action-specific parameters are added as extra query parameters (for example &authmethod=userpass&limit=100). Copy the exact base URL (including your id and key) from your plan's API page; treat the key like a password.

#Responses

Every response is JSON. A successful call returns status: "ok" with the action's data merged at the top level; most actions return no message key, so do not rely on one. A failed call returns status: "error" and a human-readable message (some errors also include a machine-readable code).

{
  "status": "ok",
  "proxies_list": ["gw-2312.coldproxy.com:30000:USERNAME:PASSWORD"]
}

{
  "status": "error",
  "message": "Something went wrong."
}

Errors also carry a meaningful HTTP status you can branch on:

Most actions require the service to be Active. Exceptions: bandwidthoptions, speedtiers, and upgradespeed also answer on non-active services; renewservice works on Active or Suspended services (other statuses return INVALID_STATUS); buybandwidth needs Active.

#Rate limits

Write actions are throttled per service. Within each limit you can call freely; beyond it the API returns HTTP 429 with code: "RATE_LIMITED" and a retry_after field (plus a Retry-After header).

reboot has its own separate 15-minute cooldown; see the reboot section below.

#Proxy API scope by product

Which commands the proxy API exposes depends on which of the four ColdProxy products the plan is, and on the features enabled for the service:

• Premium Residential Geo Target IPv4 (Unmetered) — speed-tier (Mbps) plan, 195+ countries, sticky sessions 5s–24h, billed hourly/daily/weekly/monthly. Geo, speed-tier, and standard service commands. See /proxy/residential-ipv4-unlimited/.
• Premium Residential Geo Target IPv4 (GB Based) — monthly traffic packs (per-GB), 195+ countries, sticky sessions 5s–24h, monthly billing. The product where Usage, Bandwidth Options, and Buy Bandwidth apply. See /proxy/residential-ipv4-gb/.
• Residential IPv6 — speed-tier (Mbps), USA-only, includes a /32 subnet, sticky sessions 5s–FOREVER, billed hourly/daily/weekly/monthly. See /proxy/residential-ipv6/.
• Datacenter IPv6 — speed-tier (Mbps), 25 supported countries (47 locations) plus an "All Country" random option, private /48 per location, sticky sessions 5s–FOREVER, billed daily/weekly/monthly. See /proxy/datacenter-ipv6/.

#Service overview

#info

Returns the service details: server IP and hostname, the user-auth and IP-auth port ranges, current authorized IPs, enabled geo-targeting dimensions, your proxy username and password, and the available/maximum proxy quantity. Use it as the first call in any automation.

?a=info

{
  "status": "ok",
  "server_hostname": "gw-2312.coldproxy.com",
  "user_ports": "30000-34999",
  "ip_auth_ports": "30000-34999",
  "geo_targeting": ["country", "state", "city"],
  "max_quantity": 100000,
  "max_ip_auth": 50
}

#plans

Lists the active plan(s) on the service (proxy type, thread/bandwidth limits, throughput) after client-safe sanitization.

?a=plans

#usage

Returns bandwidth usage and connection status for the service: total quota, used and remaining bytes (raw and human-readable), and live connection/throughput status. Most relevant on the Residential IPv4 (GB Based) traffic-pack plan.

?a=usage

#Proxy access

#proxies

Generates ready-to-use proxy strings for the service. One action serves both authentication modes; choose with authmethod.

?a=proxies&authmethod=userpass&limit=100&protocol=http&addprotocol=yes&country=US

{
  "status": "ok",
  "proxies_list": [
    "http://gw-2312.coldproxy.com:30000:USERNAME:PASSWORD",
    "http://gw-2312.coldproxy.com:30001:USERNAME:PASSWORD"
  ]
}

#password

Rotates the service's proxy password. ColdProxy auto-generates a new random password and returns it; you do not supply your own value. Any user:pass proxy strings you issued previously stop authenticating, so re-generate your list with proxies afterward.

?a=password

{
  "status": "ok",
  "message": "Password regenerated successfully.",
  "password": "newSecretPass456"
}

#authip

Manages the IP-authentication allow-list. One action with a method sub-parameter.

?a=authip&method=add&ip=198.51.100.24

?a=authip&method=set&ips[]=198.51.100.24&ips[]=198.51.100.25

The aliases get, remove, and replace also work; they map to list, delete, and set. If IP authentication is not enabled for the service, authip returns a 400 error.

#Geo data

These read the geo dimensions you can target. Feed the returned tokens into the proxies geo parameters, your username tags, or SuperPort rules. They are available only when the matching dimension is enabled on your plan.

?a=countries
?a=states&country=US
?a=cities&country=US&state=CA
?a=isps&country=US&state=CA&city=los-angeles

countries returns code/label pairs; states, cities, and isps each narrow within the parameters you supply (isps requires country, state, and city). When a region has no listed providers, isps returns a plain OK instead of a list.

#Routing & rules

#superports

Manages fixed routing port maps that bind geo/session settings to a port range: the geo path for IP-authenticated traffic. One action with a method sub-parameter. SuperPorts are included on every ColdProxy plan; a service with the feature switched off returns 400 with the message "SuperPorts are not enabled for this service."

?a=superports&method=add&port_start=30000&port_end=30099&country=US&sticky_time=10m

#blacklist

Manages per-service blacklist rules for domains or ports.

?a=blacklist&method=add&value=example.com&type=domain

#Billing

These read purchase options and run credit-backed billing actions. They appear when the matching capability is available for your plan.

#bandwidthoptions / buybandwidth (GB plans)

bandwidthoptions lists the bandwidth packs you can buy (with current prices); buybandwidth purchases one using account credit. Pair buybandwidth with usage to top up before the current pack runs out.

Each buybandwidth call is a separate, independent GB allocation added on top of your plan; it does not change the plan itself or its renewal/due date. The purchase is processed instantly from your account credit with no separate invoice, so the added gigabytes are available right away.

?a=bandwidthoptions
?a=buybandwidth&bandwidth=50

#speedtiers / upgradespeed (speed-tier plans)

speedtiers lists the current tier and available upgrades (in Mbps); upgradespeed moves the service to a higher tier, paid from account credit.

?a=speedtiers
?a=upgradespeed&speed=100

A successful upgradespeed can reboot the proxy server in the background. Treat it like reboot: the proxies may be unavailable for a few minutes; verify them afterward before resuming automation.

#renewservice

Renews the service for one billing period, paid from account credit. Use it to keep a plan active in automation without a manual checkout.

A renewal extends the service by exactly one billing period of the plan type (an hourly plan by +1 hour, daily by +1 day, weekly by +1 week, monthly by +1 month) and the new period starts when the current one ends, so renewing early does not lose remaining time. Renewal charges appear as Service Renewal on your account.

?a=renewservice

If your account credit cannot cover the renewal, the error response includes code, invoice_id, required_amount, and available_credit: everything an automation needs to top up and retry.

#Infrastructure

#reboot (Unmetered IPv4, Residential IPv6, Datacenter IPv6)

Reboots the proxy server. The reboot runs in the background and the proxy may be unavailable for up to 5 minutes, with a 15-minute cooldown between reboots. During the cooldown the API returns 429 with the remaining wait time; while a server (re)install is running, reboot returns 409.

?a=reboot

#After provisioning

Residential IPv4 (GB Based) and Residential IPv6 activate instantly after payment clears. Residential IPv4 (Unmetered) and Datacenter IPv6 begin automatic setup after payment clears; allow up to 10 minutes and connect as soon as setup completes. If a new service returns an authentication error, check the credentials and service status before retrying. See Activation and setup times, then verify with the Proxy Checker and My IP.