Help Guides

Trusted Proxies Client API

The Client API lets you manage your account from your own scripts and applications: list the proxy servers on your account, manage your whitelisted (authorised) IP addresses, trigger a manual rotation on a rotating proxy server, and read your usage figures.

The basics

• Endpoint: https://api.trustedproxies.com/
• Method: HTTP POST for every call, with parameters sent form-encoded (application/x-www-form-urlencoded)
• Response: JSON
• Authentication: your API key, sent as the apikey parameter with every request. You will find your API key in the Client Area under the API section. If you cannot see an API section, open a support ticket and we will enable it for you.
• Rate limit: 50 requests per minute per API key. Exceeding it returns an error telling you how many seconds to wait.

Treat your API key like a password. If it is ever exposed, re-generate it from the Client Area.

Quick start

With curl:

curl -X POST https://api.trustedproxies.com/ \
  -d "apikey=YOUR_API_KEY" \
  -d "action=listproxy" \
  -d "subaction=dns"

With Python (uses the requests library):

import requests

API_URL = "https://api.trustedproxies.com/"
API_KEY = "YOUR_API_KEY"

def tp_api(**params):
    response = requests.post(API_URL, data={"apikey": API_KEY, **params}, timeout=30)
    return response.json()

# List the proxy servers on your account, by DNS name
print(tp_api(action="listproxy", subaction="dns"))

With PHP:

<?php
function tp_api(array $params) {
    $params["apikey"] = "YOUR_API_KEY";
    $ch = curl_init("https://api.trustedproxies.com/");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    $json = curl_exec($ch);
    curl_close($ch);
    return json_decode($json, true);
}

print_r(tp_api(["action" => "listproxy", "subaction" => "dns"]));

The examples below all use the Python helper. Every call is the same pattern: change the parameters, nothing else.

1. List your proxy servers — by DNS name

tp_api(action="listproxy", subaction="dns")

Returns every proxy on your account with its DNS hostname — the name you point your software at. Example response:

[
  {"dnsname": "shp-yourcompany-us-v00001.tp-ns.com", "country": "US", "label": "Virtual Dedicated Proxy Server"},
  {"dnsname": "cld-us-abcd.tp-ns.com", "country": "US", "label": "Proxy Server Cloud"}
]

The label field describes the service each entry belongs to; the exact wording varies by product. Country codes are two-letter ISO codes.

2. List your proxy servers — by IP address

tp_api(action="listproxy", subaction="ip")

The same list, with IP addresses instead of DNS names:

[
  {"ip": "203.0.113.10", "country": "US", "label": "Virtual Dedicated Proxy Server"},
  {"ip": "198.51.100.24", "country": "GB", "label": "Proxy Server Cloud"}
]

We recommend connecting by DNS name rather than IP wherever possible: if we ever need to move a proxy to a new address, the DNS name follows it automatically and your configuration keeps working.

3. List your whitelisted IP addresses

tp_api(action="setmyip", subaction="list")

Returns the IP addresses currently authorised to use your proxies:

[
  {"StaticIP": "198.51.100.7"},
  {"StaticIP": "203.0.113.21"}
]

If no IPs are whitelisted on the account, an error is returned saying so.

4. Replace your whitelisted IP addresses

tp_api(action="setmyip", subaction="deleteandadd",
       staticip="198.51.100.7,203.0.113.21")

Important: this replaces your entire whitelist. The comma-separated list you send becomes the complete new whitelist — any address you leave out is removed. Always send the full list you want active, not just the additions.

Rules:

• Public IPv4 addresses only. Private-range addresses (10.x, 172.16–31.x, 192.168.x, 127.x, 169.254.x) are ignored — whitelist the public IP your traffic leaves from.
• Invalid entries are skipped and named in the response; the valid ones are still applied.
• Each account has a maximum number of whitelisted IPs. If you send more than your limit, the request is rejected and the error tells you your limit. Contact support if you need it raised.

Successful response:

{"Success200": "All valid IP addresses were whitelisted successfully."}

5. Manually rotate a rotating proxy server

tp_api(action="cloudrotate", iporname="cld-us-abcd.tp-ns.com")

Triggers an immediate IP rotation on one of your rotating proxy servers. iporname accepts either the DNS name or the IP address of the rotator, exactly as returned by listproxy. The rotator must belong to your account.

{"Success200": "Successfully Rotated."}

If rotation fails, the error message includes a code — quote it when contacting support.

6. Usage report

tp_api(action="getusage")

Returns your quota and usage for today and for the current billing period. Available on accounts with a usage-metered service (rotating / Big-G); other accounts receive an error saying the report does not apply.

Example response for an account billed per request (GET billing):

{
  "username": "yourcompany",
  "service": "Cloud",
  "anniversary_day": "15",
  "quota": "100,000",
  "se_quota": "50,000",
  "billable_gets_today": "1,234",
  "billable_se_gets_today": "1,180",
  "errors_today": "12",
  "billable_gets_month_to_date": "18,540",
  "billable_se_gets_month_to_date": "17,995",
  "errors_month_to_date": "141",
  "report_date": "2026-08-22"
}

Accounts billed by bandwidth receive the same report with bandwidth fields instead (billable_bw_today, billable_bw_month_to_date, and so on) with values in GB.

Notes on reading the report:

• Month to date runs from your billing anniversary day (the anniversary_day field), not from the 1st of the calendar month.
• se_ fields are the search-engine subtotal (Google, Yahoo and Bing) of the overall figure.
• Requests that returned errors are shown separately and are not billable.
• Numeric values are returned as formatted strings (for example "18,540") — strip the commas before doing arithmetic on them.

Errors

Errors are returned as JSON with a matching HTTP status code:

If a call returns empty or null results unexpectedly, check that you are using your current API key — re-generating the key in the Client Area invalidates the old one.

Reference: all parameters

Questions, or need something the API does not cover? Open a support ticket — we are happy to help.