15% off your first purchase with code WELCOME15, up to 25 GB.

See pricing
ARC Proxies

Integration · HTTP clients

How to use a proxy with Axios

Axios takes a proxy in Node.js through its proxy option: protocol, host, port and an auth object. Since Axios 1.16.1, HTTPS targets are tunnelled through CONNECT with that option alone. On older versions, use https-proxy-agent as the httpsAgent and set proxy: false.

Reviewed 30 Oct 2026

your proxy, as a URL
http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000

The short answer

  • On Axios 1.16.1+, proxy: { protocol, host, port, auth } handles HTTP and HTTPS targets.
  • On older versions, the proxy option did not tunnel HTTPS properly; httpsAgent: new HttpsProxyAgent(url) with proxy: false is the safe route.
  • proxy is Node-only; Axios in the browser ignores it.
  • A rejected tunnel comes back as error.response.status === 407; do not retry it.

Setup

Set up Axios with a proxy, step by step

  1. 01

    Install Axios and check the version

    The version decides which setup to use. https-proxy-agent and socks-proxy-agent are only needed for older Axios and for SOCKS5.

    shell
    npm i axiosnpm ls axios              # 1.16.1 or later: the proxy option is enoughnpm i https-proxy-agent   # only for older Axiosnpm i socks-proxy-agent   # only for SOCKS5
  2. 02

    Use the proxy option and check the exit

    Host, port and credentials are separate fields. The echo service returns the exit the target sees.

    check-exit.mjs
    import axios from 'axios';const res = await axios.get('https://api.ipify.org?format=json', {  proxy: {    protocol: 'http',    host: 'proxy.arcproxies.io',    port: 8000,    auth: { username: 'USERNAME_pool-arcfast_country-de', password: 'PASSWORD' },  },  timeout: 30_000,});console.log(res.data);   // { ip: '…' }
  3. 03

    On Axios before 1.16.1: https-proxy-agent

    Hand the tunnelling to an agent and switch Axios' own proxy handling off, including the environment variables it would otherwise read.

    legacy.mjs
    import axios from 'axios';import { HttpsProxyAgent } from 'https-proxy-agent';const agent = new HttpsProxyAgent('http://USERNAME_pool-arcfast_country-de:PASSWORD@proxy.arcproxies.io:8000');const res = await axios.get('https://api.ipify.org?format=json', {  httpsAgent: agent,  proxy: false,  timeout: 30_000,});console.log(res.data);
  4. 04

    One Axios instance per sticky session

    axios.create() bakes the proxy into an instance. A task that should keep one exit gets an instance with its own _session- handle.

    sticky.mjs
    import axios from 'axios';import { randomBytes } from 'node:crypto';function stickyClient(minutes = 10) {  const handle = randomBytes(4).toString('hex');  return axios.create({    timeout: 30_000,    proxy: {      protocol: 'http',      host: 'proxy.arcproxies.io',      port: 8000,      auth: {        username: `USERNAME_pool-arcfast_country-de_session-${handle}_sesstime-${minutes}`,        password: 'PASSWORD',      },    },  });}const client = stickyClient();for (let page = 1; page <= 3; page++) {  const { status } = await client.get('https://example.com/search', { params: { q: 'lamp', page } });  console.log(page, status);}
  5. 05

    Geo-target per request

    Country and city are username tokens, so a per-request proxy with a different username switches market. Cities come from the published list, lowercased without spaces.

    geo.mjs
    const MARKETS = {  'us-chicago': 'USERNAME_pool-arcfast_country-us_city-chicago',  'br':         'USERNAME_pool-arcfast_country-br',  'de':         'USERNAME_pool-arcfast_country-de',};for (const [market, username] of Object.entries(MARKETS)) {  const { status } = await axios.get('https://example.com/pricing', {    proxy: { protocol: 'http', host: 'proxy.arcproxies.io', port: 8000, auth: { username, password: 'PASSWORD' } },    timeout: 30_000,  });  console.log(market, status);}
  6. 06

    Retry the right errors

    Stop on 407. Retry 429, 5xx and timeouts with backoff, each attempt on a new handle so a bad exit is not reused.

    fetch.mjs
    import axios from 'axios';import { randomBytes } from 'node:crypto';import { setTimeout as sleep } from 'node:timers/promises';async function fetchWithRetry(url, attempts = 4) {  for (let attempt = 0; attempt < attempts; attempt++) {    const username = `USERNAME_pool-arcfast_country-de_session-${randomBytes(4).toString('hex')}_sesstime-5`;    try {      return await axios.get(url, {        proxy: { protocol: 'http', host: 'proxy.arcproxies.io', port: 8000, auth: { username, password: 'PASSWORD' } },        timeout: 30_000,      });    } catch (err) {      if (!axios.isAxiosError(err)) throw err;      const status = err.response?.status;      if (status === 407) throw new Error('proxy rejected the credentials');      const retryable = status === 429 || status >= 500 ||        ['ECONNABORTED', 'ETIMEDOUT', 'ECONNRESET'].includes(err.code);      if (!retryable) throw err;      await sleep(1000 * 2 ** attempt);    }  }  throw new Error(`gave up on ${url}`);}

Which Axios proxy setup for which version

Axios versionHTTPS targets via `proxy` optionRecommended setup
1.16.1 and laterTunnelled through CONNECT, TLS end to endproxy: { protocol, host, port, auth }
Earlier 1.x and 0.xNot tunnelled correctlyhttpsAgent: new HttpsProxyAgent(url) plus proxy: false
Any, with SOCKS5Not applicablehttpAgent/httpsAgent: new SocksProxyAgent('socks5h://…') plus proxy: false

Axios' own docs now state that for https:// targets it "establishes a CONNECT tunnel through the proxy and performs TLS end-to-end with the origin", sends Proxy-Authorization only on the CONNECT request, and leaves tunnelling to an HttpsProxyAgent if you supply one. The 1.16.1 release notes record the fix for HTTPS data reaching an HTTP proxy in cleartext under some configurations, a good reason to upgrade rather than work around it.

Rotating vs sticky with Axios

A rotating username lets each new connection take a new exit. Node's agents keep connections alive, and an HTTPS request runs in a CONNECT tunnel that stays on one exit, so consecutive requests may share an IP. Use a fresh _session- handle when you need a new IP, and a fixed one when you need to keep it; rotating vs sticky sessions has the decision guide.

SOCKS5 with Axios

Axios has no SOCKS support of its own. socks-proxy-agent provides it: create new SocksProxyAgent('socks5h://{{USER}}:{{PASS}}@{{GATEWAY}}'), pass it as both httpAgent and httpsAgent, and set proxy: false. socks5h resolves hostnames at the gateway. Same port and credentials as HTTP; see SOCKS5 for when it is worth it.

The problem

Common pitfalls

Environment variables winning silently

Axios reads http_proxy and https_proxy by default. If your code sets httpsAgent without proxy: false, a stray variable can still interfere.

Expecting proxy to work in the browser

The proxy option is Node-only. Browser code goes through the browser's own network stack and proxy settings.

Credentials in host

host is just the hostname. Credentials belong in auth, port in port as a number.

Retrying 407

A generic "retry on any error" interceptor will hammer the gateway with bad credentials. Exclude 407 explicitly.

FAQ

Questions

Something not covered? Write to contact@arcproxies.io.

How do I use a proxy with authentication in Axios?

Pass proxy: { protocol: 'http', host, port, auth: { username, password } } in the request config or in axios.create(). On Axios 1.16.1 and later this works for HTTPS targets too.

Why do HTTPS requests through a proxy fail with older Axios?

Before 1.16.1, Axios' proxy option did not tunnel HTTPS targets the way most proxies expect. Upgrade, or use httpsAgent: new HttpsProxyAgent('http://user:pass@host:port') together with proxy: false.

Does Axios support SOCKS5 proxies?

Not directly. Use socks-proxy-agent: pass new SocksProxyAgent('socks5h://user:pass@host:port') as httpAgent and httpsAgent, and set proxy: false.

How do I get a new IP for each Axios request?

Give each request its own _session- handle in the proxy username. Without one, rotation happens per new connection, and kept-alive connections can reuse the same exit.

Sources & review

Last reviewed by the ARC Proxies team. Prices are read from the live catalog at build time.

  1. [1]Axios: Request config: proxy
  2. [2]axios/axios: Release v1.16.1
  3. [3]GitHub, TooTallNate/proxy-agents: https-proxy-agent README
  4. [4]GitHub, TooTallNate/proxy-agents: socks-proxy-agent README

Next

What people build with it

Use caseProxies for web scraping and data collectionA second provider that just works — Scrapy, requests, Crawlee or Playwright, self-serve, no sales call, bandwidth that never expires.Use caseProxies for price and competitor monitoringSee the price a shopper in Berlin, Lyon or Chicago sees. ISP bandwidth at our lowest price per GB for HTML checks, residential where a marketplace is strict.Use caseProxies for brand protection & MAP monitoringFind counterfeit listings, unauthorised resellers and minimum-advertised-price violations that are only shown to consumer IPs in a given region.GlossaryHTTP CONNECTHTTP CONNECT is the HTTP request method a client sends to a proxy to ask for a tunnel to a host and port; once the proxy answers with a 2xx status it blindly forwards bytes in both directions, which is how HTTPS passes through an HTTP proxy with TLS intact end to end (RFC 9110, section 9.3.6).GlossarySOCKS5SOCKS5 is a proxy protocol, standardised in RFC 1928 in 1996, that relays TCP connections and UDP datagrams between a client and a destination without interpreting the application traffic, with username/password authentication defined separately in RFC 1929.GuideRotating vs sticky sessionsRotating proxies change exit IP per connection; sticky sessions hold one IP for a set time. How each works, when to use which, and how to set them up.IntegrationNode.js fetchNode's built-in fetch has no proxy option. Use undici's ProxyAgent as the dispatcher, or NODE_USE_ENV_PROXY, with sticky sessions, SOCKS5 and 407 handling.

Integrations

Other http clients

Python requestsUse an authenticated proxy with Python requests: the proxies argument, sticky sessions per task, geo-targeting, SOCKS5 and retries that skip 407 errors.HTTPXConfigure an authenticated proxy in HTTPX 0.28: the proxy= argument that replaced proxies=, mounts per domain, async clients, SOCKS5 and error handling.aiohttpUse an authenticated proxy with aiohttp: proxy= per request or per session, why proxy_auth is deprecated, SOCKS5 through aiohttp-socks, and 407 handling.Node.js fetchNode's built-in fetch has no proxy option. Use undici's ProxyAgent as the dispatcher, or NODE_USE_ENV_PROXY, with sticky sessions, SOCKS5 and 407 handling.curlSend curl through an authenticated proxy with -x and -U, check the exit IP, test sticky sessions and countries, use socks5h, and read 407 failures.GoRoute Go's net/http through an authenticated proxy: Transport.Proxy with url.UserPassword, a sticky session per request context, SOCKS5 and 407 checks.RubyUse an authenticated proxy in Ruby: Net::HTTP proxy arguments, Faraday proxy options, sticky sessions per task, geo-targeting and 407 handling.PHP GuzzleRoute PHP Guzzle and plain cURL through an authenticated proxy: the proxy option, sticky sessions, geo-targeting, retries that stop on a 407.Java HttpClientUse an authenticated proxy with java.net.http.HttpClient: ProxySelector, Authenticator, the Basic-over-CONNECT setting, sticky sessions and 407s.C# HttpClientUse an authenticated proxy in .NET: WebProxy and NetworkCredential on SocketsHttpHandler, a client per sticky session, SOCKS5 and 407 handling.Rust reqwestRoute Rust reqwest through an authenticated proxy: Proxy::all with basic_auth, a Client per sticky session, socks5h, timeouts and 407 errors.wgetRun GNU Wget through an authenticated proxy: https_proxy, --proxy-user, a .wgetrc for credentials, sticky sessions for mirrors and exit codes.PostmanSend Postman requests through an authenticated proxy: the custom proxy settings, Proxy auth, checking the exit IP, sessions, countries and Newman.DockerGive Docker containers and builds an authenticated proxy: HTTP_PROXY, HTTPS_PROXY and NO_PROXY, build args, Compose, and why the daemon proxy differs.

Get started

Get credentials and paste them in.

Sign up, buy a gigabyte, generate a username in the dashboard. Code WELCOME15 takes 15% off your first purchase; bandwidth never expires.

Create your accountQuestions first? contact@arcproxies.io