Buying Guides 5 min read

Proxies With API Access: Automating Proxy Use in Your Code

Two APIs matter when you automate proxies: the provider's account API and the gateway itself. Here's how to use both well.

Proxies with API access matter as soon as proxies stop being something you paste into a browser and become part of a system. A scraper that runs nightly, a SaaS that gives each customer their own IPs, or a reseller shop that delivers plans automatically all need to manage proxies from code. This post covers what a provider API is for, how to treat the proxy gateway itself as an API, and patterns that keep automated setups reliable.

Two Different APIs

  • The account or management API: an HTTP API on the provider's side for things like plans, balance, usage and sub-users. You call it with an API key.
  • The gateway: the proxy endpoint itself. Its behaviour is controlled by your username string, so building that string in code is effectively an API call.

Most automation needs both: the management API to keep plans topped up and monitored, and programmatic usernames to control country and sessions per request.

What a Management API Is Useful For

  • Checking remaining bandwidth before a job starts, so it doesn't fail halfway with a 402.
  • Alerting when usage spikes, which often signals a retry loop bug.
  • Creating plans or sub-users automatically for customers if you run a platform or resell.
  • Pulling usage data into your own dashboards or billing.

When comparing providers, read the API documentation before you buy. Look for clear authentication, documented error responses and examples. If the docs are vague, building on them will be painful.

Treat the Gateway as an API

On a gateway where options live in the username, a small helper function gives you a clean interface for every request:

import os
import uuid

BASE_USER = os.environ['PROXY_USER']
PASSWORD = os.environ['PROXY_PASS']
HOST = 'global.nodeproxies.xyz'

def proxy_url(country=None, session=None, minutes=10, socks=False):
    user = BASE_USER
    if country:
        user += '-country-' + country
    if session:
        user += '-session-%s-time-%d' % (session, minutes)
    if socks:
        return 'socks5h://%s:%s@%s:1080' % (user, PASSWORD, HOST)
    return 'http://%s:%s@%s:8080' % (user, PASSWORD, HOST)

# new IP per request in Germany
print(proxy_url(country='de'))
# one US IP held for 30 minutes
print(proxy_url(country='us', session=uuid.uuid4().hex[:8], minutes=30))

Keep credentials in environment variables or a secret manager, never in source control. If your password contains special characters, URL-encode it with urllib.parse.quote before building the URL. Our proxy username builder shows the same options interactively.

Handle Gateway Status Codes in Code

Your automation should react differently to proxy errors and target errors:

import requests

def fetch(url, proxy):
    try:
        r = requests.get(url, proxies={'http': proxy, 'https': proxy}, timeout=30)
    except requests.exceptions.ProxyError as e:
        msg = str(e)
        if '407' in msg:
            raise SystemExit('Proxy auth failed: check credentials or plan status')
        if '402' in msg:
            raise SystemExit('Plan out of bandwidth: top up before retrying')
        return None  # transient proxy error, retry later with backoff
    if r.status_code in (403, 429):
        return None  # target is limiting you: slow down or rotate
    return r

With HTTPS targets, requests surfaces gateway errors on CONNECT as a ProxyError whose message includes the status. A 407 means wrong credentials or an inactive plan, and retrying won't help. A 402 means the plan is out of bandwidth. See how to fix proxy error 407 and python requests ProxyError.

Patterns for Reliable Automation

  1. Check bandwidth before large jobs and stop gracefully below a threshold.
  2. Cap retries per URL and use exponential backoff, so a block doesn't burn your plan.
  3. Log the session id with each result, so you can trace problems to an IP.
  4. Generate session ids per task (per account, per crawl) rather than reusing one globally.
  5. Store separate credentials for separate products (residential, datacenter) and route by target.

Using Proxies From Node.js

The same username-building approach works in any language. In Node.js with axios, pass the proxy as an object:

const axios = require('axios');

function proxyFor(country, session) {
  let username = process.env.PROXY_USER;
  if (country) username += '-country-' + country;
  if (session) username += '-session-' + session + '-time-10';
  return {
    protocol: 'http',
    host: 'global.nodeproxies.xyz',
    port: 8080,
    auth: { username, password: process.env.PROXY_PASS },
  };
}

axios.get('https://api.ipify.org', { proxy: proxyFor('fr') })
  .then((res) => console.log(res.data))
  .catch((err) => console.error(err.message));

More Node.js patterns, including Puppeteer, are in proxies with Node.js, axios and Puppeteer.

API Access on NodeProxies

NodeProxies has an API documented in the docs, alongside a dashboard proxy generator and a reseller program for platforms that deliver proxies to their own customers. The gateway takes country and session options in the username on both HTTP (8080) and SOCKS5 (1080). Plans start at 100 MB with no subscription; see the pricing page or register. For background on building automated resale, read how to become a proxy reseller.

FAQ

Do I need an API to use proxies in code?

No. Any HTTP library can use a proxy URL directly. A management API is for automating plans, usage checks and sub-users.

How do I rotate proxies through an API?

On a rotating gateway you don't need an API call: every request without a session gets a new IP. Change the session id when you want a new sticky IP.

How do I keep proxy credentials secure in code?

Load them from environment variables or a secret manager, never commit them, and rotate the password if it leaks.

Where is the NodeProxies API documentation?

In the NodeProxies docs, which also list the connection details and username options.

NodeProxies

Ready to get started?

90M+ residential, mobile & datacenter proxies. Datacenter from $0.30/GB, residential from $0.42/GB. No contracts.

Create free account