How to use a proxy with Axios

Your proxy details

After you buy a plan, open My proxies. Choose the Proxy Type (Rotating or Sticky), the Protocol (HTTP or SOCKS5) and a Format, then copy a line. The generator offers three formats:

In the examples on this page, replace USERNAME, PASSWORD, HOST and PORT with the values from your line. SOCKS5_PORT is the port the generator shows when you pick SOCKS5.

Residential lines are either rotating (a new IP on new connections) or sticky (one IP for the time you choose). Datacenter and ISP plans give you a list of dedicated IPs, one per line as IP:PORT:USERNAME:PASSWORD, and each line is one fixed IP.

To test a line, open https://ipinfo.io/json through it: it shows the exit IP and country. For HTTP lines you can also use the free proxy checker.

The built-in proxy option

npm install axios

import axios from 'axios';

const { data } = await axios.get('https://ipinfo.io/json', {
  proxy: {
    protocol: 'http',
    host: 'HOST',
    port: PORT, // the port number from the generator
    auth: { username: 'USERNAME', password: 'PASSWORD' },
  },
  timeout: 30000,
});
console.log(data);

Use Axios 1.16.1 or later for HTTPS sites. Earlier versions could, in some setups, send HTTPS requests to an HTTP proxy unencrypted instead of through a CONNECT tunnel. On older versions, use the agent below.

Keep protocol: 'http' even for HTTPS sites: it describes how Axios talks to the proxy, and the site traffic stays encrypted inside the tunnel.

With https-proxy-agent (any Axios version)

npm install axios https-proxy-agent

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://USERNAME:PASSWORD@HOST:PORT');

const { data } = await axios.get('https://ipinfo.io/json', {
  httpsAgent: agent,
  proxy: false, // don't let axios apply its own proxy logic or HTTP_PROXY variables
  timeout: 30000,
});
console.log(data);

proxy: false stops Axios from mixing its own proxy handling, or HTTP_PROXY and HTTPS_PROXY variables, into the agent’s connection. An agent also gives you control over connection reuse (see below).

A reusable Axios instance

Add http-proxy-agent as well if you also call plain http:// URLs.

npm install http-proxy-agent

import axios from 'axios';
import { HttpProxyAgent } from 'http-proxy-agent';
import { HttpsProxyAgent } from 'https-proxy-agent';

const PROXY = 'http://USERNAME:PASSWORD@HOST:PORT';

export const client = axios.create({
  httpAgent: new HttpProxyAgent(PROXY),
  httpsAgent: new HttpsProxyAgent(PROXY),
  proxy: false,
  timeout: 30000,
});

const { data } = await client.get('https://ipinfo.io/json');
console.log(data.ip, data.country);

Rotating and sticky IPs

Rotation happens per connection. A rotating line gets a new IP when your client opens a new connection; requests sent through the same open HTTPS tunnel leave from the same IP. By default, both the built-in option and https-proxy-agent open a new tunnel for each request, so a rotating line gives you a new IP per request. With new HttpsProxyAgent(url, { keepAlive: true }), connections are reused: faster, but the IP stays the same while a connection is open.

To make sticky lines, open the generator, set Proxy Type to Sticky, choose a Sticky Duration if your plan offers one, set how many lines you want in Sticky Amount, then copy or download them. Each line keeps its IP for the chosen time. The session part of a sticky username differs by plan, so always generate sticky lines instead of editing usernames by hand. Create one agent (or one Axios instance) per sticky line.

Target a country

On residential plans, add -country- and a two-letter country code to the end of the username, for example USERNAME-country-us or USERNAME-country-gb. To combine a country with a state, a city or a sticky session, build the line in the generator, which shows only the options your plan supports. Datacenter and ISP IPs have a fixed location that you choose when you buy them.

const agent = new HttpsProxyAgent('http://USERNAME-country-fr:PASSWORD@HOST:PORT');

SOCKS5

npm install socks-proxy-agent

import axios from 'axios';
import { SocksProxyAgent } from 'socks-proxy-agent';

const agent = new SocksProxyAgent('socks5h://USERNAME:PASSWORD@HOST:SOCKS5_PORT');

const { data } = await axios.get('https://ipinfo.io/json', {
  httpAgent: agent,
  httpsAgent: agent,
  proxy: false,
});
console.log(data);

Use socks5h:// so the proxy resolves hostnames. Use the SOCKS5 port from the generator.

Tips

• Axios in a web browser can’t choose a proxy; the browser controls networking. These examples are for Node.js.
• Keep the agent outside your request function and reuse it, unless you want a new tunnel per request on purpose.

Troubleshooting

• Status 407 from the proxy

  The username or password is wrong or wasn’t sent. Check the line and URL-encode special characters.More on this error →

• EPROTO or “wrong version number” on HTTPS sites

  The proxy is set to https. Use protocol: 'http' (or an http:// agent URL); the site traffic is still encrypted inside the tunnel.More on this error →

• HTTPS sites fail through the built-in option on an old Axios

  Upgrade to Axios 1.16.1 or later, or use https-proxy-agent with proxy: false.

• The IP doesn’t change on a rotating line

  Your client is reusing an open connection. Requests that share a tunnel share its IP. Open a new connection per request, or use one sticky line per task.More on this error →

• Timeouts

  Set an explicit timeout of 30–60 seconds, retry on a new connection, and lower concurrency.More on this error →

Seeing another error? Read proxy errors and how to fix them, or contact support.

Questions