proxytoo

How to Set Up a Proxy: From Username to Scraper

Once you know what each part of the username does, proxy setup in any tool takes a few minutes. This page covers tool by tool setup, error fixes and how to keep your token safe.

Get a token and start

1. Create an account and save your access token

Get an access token on the sign up page. The token is your password for logging in and for connecting to the proxy. The server doesn't keep it, so save it as a .txt file.

Get started

2. Top up your balance

Pick an amount in the top up box on the dashboard and send the request. You can top up from $30, and it is added to your balance once payment is confirmed.

See pricing

3. Build the username

Put a country, city and session in the username to set the location and how long the IP is kept. Pick them under make connection details in the dashboard and it is built for you.

Username examples

New IP per request
user-country-us
City targeting
user-country-us-city-new_york
Keep the same IP
user-country-us-session-shop1
Mobile IP
user-type-mobile-country-us

4. Test the connection

Send a request with curl and check the IP and country in the response.

Connection format

HTTP

http://user-country-us:YOUR_TOKEN@gate.proxytoo.com:7000

SOCKS5

socks5://user-country-us:YOUR_TOKEN@gate.proxytoo.com:7000

curl

curl -x http://gate.proxytoo.com:7000 -U "user-country-us:YOUR_TOKEN" https://ipinfo.io/json

5. Add it to your tools

Enter the host, username and token in Python, Node.js or your browser automation tool.

Code examples

Python (requests)

import requests

proxy = "http://user-country-us:YOUR_TOKEN@gate.proxytoo.com:7000"
res = requests.get("https://ipinfo.io/json",
                   proxies={"http": proxy, "https": proxy})
print(res.json())

Node.js (undici)

import { ProxyAgent, fetch } from "undici";

const agent = new ProxyAgent("http://user-country-us:YOUR_TOKEN@gate.proxytoo.com:7000");
const res = await fetch("https://ipinfo.io/json", { dispatcher: agent });
console.log(await res.json());

Puppeteer

const browser = await puppeteer.launch({
  args: ["--proxy-server=http://gate.proxytoo.com:7000"],
});
const page = await browser.newPage();
await page.authenticate({ username: "user-country-us", password: "YOUR_TOKEN" });
await page.goto("https://ipinfo.io/json");

When connections fail

  • 407 Proxy Authentication Required

    The username or token doesn't match. Check that you pasted them exactly, with no extra spaces.

  • Connection timed out

    If you targeted a city, try again with only the country. Also check whether a company firewall is blocking port 7000.

  • A site keeps blocking you

    Space out your requests more and change the IP on every request. For sites with strong blocking, residential proxies are the right fit.

How do I read a proxy username?

A proxy username is a short settings string made of parts joined by hyphens. It starts with user, then adds name and value pairs that set the exit location and how long the IP is kept. Once you know the parts, you can write any connection string by hand without opening the dashboard.

After country comes a two letter country code in lowercase. user-country-us means a US IP and user-country-jp means a Japanese IP. After city comes the city name in lowercase with spaces turned into underscores, as in user-country-us-city-new_york.

After session comes a session name you choose. With user-country-jp-session-shop1, every request using that name keeps the same IP for up to 120 minutes. Add type-mobile, as in user-type-mobile-country-gb, to exit through a mobile IP.

The password field always takes your access token, which starts with pt_. To change location or session, edit only the username and leave the token as it is.

  • user marks the start of the settings.
  • country plus a two letter code picks the country.
  • city plus an underscored name picks the city.
  • session plus a name keeps the same IP.
  • type-mobile picks a mobile IP.

HTTP vs SOCKS5 proxy: which one should I use?

HTTP proxies are the easy default for web scraping and browser work, while SOCKS5 proxies fit non web traffic or setups where you want DNS resolved on the proxy side. ProxyToo accepts both on one gateway, gate.proxytoo.com:7000. Keep the same username and token and change only the scheme at the front of the address.

HTTP proxies were built for web requests, so almost every library and browser understands them out of the box. HTTPS sites work too, because the proxy opens an encrypted tunnel for the connection. For web tools like requests, Scrapy, Puppeteer and Playwright, start with the HTTP format.

SOCKS5 relays the connection itself, so it can carry many kinds of traffic beyond the web. In Python, starting the address with socks5h makes the proxy resolve hostnames in the exit country, which keeps your location consistent. Chromium based browsers have limited support for SOCKS5 with a username, so HTTP is the smoother choice for browser automation.

  • HTTP for web scraping and browser automation
  • SOCKS5 for programs that send non web traffic
  • A socks5h address to resolve DNS in the proxy country
  • The same username and token for both

How do I add a proxy to a browser or antidetect browser?

In a regular browser, open a proxy extension and enter four values in separate fields: host, port, username and token. Pick the host:port:user:pass format under Create connection details in the dashboard and all four values come on one line, ready to copy field by field. If an auth prompt appears on the first page load, enter the username and token there.

An antidetect browser gives each profile its own browser environment, so the basic rule is one username per profile. In the profile's proxy field choose HTTP or SOCKS5, then add a session part to the username with a different session name for each profile. Each profile then gets its own IP, and the IP stays the same within that profile.

Match the profile's language, time zone and location to the country you chose so pages look the way a local visitor sees them. For a profile that runs one account for a long time, ISP proxies or dedicated datacenter proxies keep the same IP for the whole term. Order either one under Buy products in the dashboard by choosing a quantity and a term.

  • One session name per profile
  • Language and time zone matched to the IP country
  • ISP proxies for long running profiles
  • Username and token in the auth prompt

How do I use a proxy with Python requests and Scrapy?

In Python, build the proxy as one line shaped like http://username:token@gate.proxytoo.com:7000 and pass it to the library's proxy setting. With requests, the key step is putting the same address in both the http and https entries. Filling both entries sends HTTPS requests through the proxy as well.

Set the proxy once on a requests Session object and every request in that session uses it. Use a country only username when you want a new IP per request, and a username with a session part for flows that carry over, like a login. For SOCKS5, install the SOCKS extra for requests and change the front of the address to socks5h.

In Scrapy, put the same style of address in each request's meta proxy value, and the built in proxy middleware turns the username and token into the auth header for you. To apply one setting to every request, write a small downloader middleware that fills in the proxy value. To split traffic into sessions, have that middleware assign a different session name to each batch of requests.

Tune concurrency and pacing with settings such as CONCURRENT_REQUESTS and DOWNLOAD_DELAY. Start low, watch for steady responses, then raise them step by step to balance speed and success. Residential proxies bill by traffic used, so filtering out images and fonts makes your balance last longer.

How do I set up a proxy in Node.js, Puppeteer and Playwright?

In Node.js, the usual approach is to create a proxy agent and hand it to your request library. For HTTP use a package such as https-proxy-agent or the ProxyAgent from undici, and for SOCKS5 use socks-proxy-agent, passing an address that holds the username and token. Create the agent once and reuse it across requests so connections are reused and stay fast.

With Puppeteer, pass only the gateway address in the --proxy-server launch argument, then send the username and token separately with page.authenticate after opening a page. Splitting them this way is the most reliable setup in Chrome. To switch country or session, the simplest route is to launch another browser with the new username.

With Playwright, set server, username and password in the proxy launch option and authentication is handled in one step. The password field takes your access token. You can also launch one browser and give each context its own proxy, so pairing one session name with each context lets a single script run several IPs side by side.

Browser automation downloads images, video and fonts on every page, which adds up to a lot of traffic. Blocking unneeded resources with request interception cuts the cost of residential and mobile proxies, which bill per GB. Adding a session name keeps the IP steady while a page loads, so pages render cleanly.

Rotating proxies or sticky sessions: which is better for scraping?

For scraping where each page is read on its own, use a new IP per request, and for flows that carry over, like a login or a cart, use a session. Without a session part the IP changes on every request, and with one the IP stays the same under that name. One token handles both, so you can pick per step of the job.

Rotating mode suits jobs where pages have no link to each other, like search results, product lists and price tables. Requests spread evenly across many IPs, so to the site they look like ordinary traffic from many visitors. Even on large crawls of one site, spacing out requests keeps things steady.

With sessions, the trick is a separate session name for each unit of work. If you check five store accounts, name them shop1 to shop5 so each account keeps its own IP. Splitting work into short flows that finish inside the session window keeps one IP for the whole flow.

If you need the same IP for a full month, ISP proxies or dedicated datacenter proxies fit best, and for high volume at a low unit price, shared datacenter proxies or IPv6 proxies are good options. For heavy traffic jobs where mixed countries are fine, unlimited residential proxies at $37.58 per day make costs easy to plan.

  • New IP per request for independent pages
  • A kept session name for login and checkout flows
  • A different session name per unit of work
  • ISP or dedicated datacenter for one IP all month

How do I check my proxy IP and fix connection errors?

The fastest check is to send a request through the proxy to a page that shows your IP, then confirm the IP and country match the country in your username. Pick the curl format under Create connection details in the dashboard and you get a ready check command to paste into a terminal. If you set a session, send the same command two or three times to confirm the IP holds.

A 407 response means the proxy did not accept your credentials, and it usually comes down to one character in the username or token. Check that the token starts with pt_, that no spaces or line breaks came along when you copied it, and that the username starts with user. If special characters end up inside the one line address, URL encoding them clears it up.

Responses like 403 or 429 come from the site, which means the proxy connection worked and the site is watching request speed or patterns. Space out requests, send browser like headers, and switch from a session to a new IP per request.

Timeouts often come from an office or school network blocking the gateway port, a narrow city target, or a short timeout in your code. Try the same command from another network, drop the city part and target only the country, and give the request a longer timeout. Also check that you have balance left and, for IP products, that the order shows In use under My orders.

  • 407 means check the username and token
  • 403 or 429 means slow down and rotate IPs
  • Timeouts mean check network, city and timeout
  • Run the same command a few times to test a session

How do I keep my proxy access token safe?

Your access token is both your account ID and your proxy password, so anyone holding it can use proxies on your balance. The server keeps only a hash of the token, which makes the token file you saved at sign up the one and only original. Keep copies in two places and add it to a password manager so it stays safe and easy to find.

Keep the token out of your code and load it from an environment variable or a separate config file. Add that config file to .gitignore so it stays out of your repository, and on a shared server tighten file permissions so only you can read it. That way you can share your code while the token stays on your own machine.

Watch your logs and screenshots too. Printing the full proxy address on an error writes the token straight into the log, so mask the token part whenever you log an address. When you post a question or a screenshot, show the username only and remove the token first.

  • Token file stored in two places
  • Token loaded from an environment variable
  • Config file kept out of the repository
  • Token masked in logs and screenshots

Using proxies responsibly

  • Collect public information, and never access other people's accounts without permission.
  • Space out requests so you don't put load on the sites you visit.
  • Proxies can't be used for spam, unauthorized access or fraud.

Related pages

Get a token and connect through the country you need

Sign up takes just one token. Top up from $30 and use every proxy type from one balance.

Get a token and start