How To Guides - All Proxies

Learn about the different IP targeting options for Bright Data’s Proxy networks, how to set limits on bandwidth consumption, whitelisting IPs, and more!

Check out our table of contents on the left to navigate through the sections below that are of interest to you. 

Integrate a new proxy into your code

To integrate the proxies into your code, please visit the API examples page, which can be accessed via your zone's settings, under "access parameters":

On this page, you can choose integration examples for most modern coding languages, just choose the integration type, your proxy zone, coding language, etc. and the page will generate a code snippet you can use right away.

Integrate a proxy into 3rd party software

Check out a few examples in the API examples page mentioned above (just choose "other software" in the "language" drop-down menu), or check our Integrations page, where we have specific guides to integrate our proxies within the most popular tools across the industry today. 

Target a Specific Country or City with Bright Data proxies


To target a specific country:

1. Make sure your specific proxy zone is configured to use IPs from that country. You can see this in your proxy zones "Configuration" tab under Geolocation Targeting

2. When sending your request, add the -country flag, after your zone’s name in the request, followed by the 2-letter ISO code for that country. 

In the example below: We added -country-us to our request, so we will send a request originating from the United States ("us").

curl--proxy --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-country-us: <ZONE_PASSWORD>  ""

EU region (Relevant for DC, ISP, and Web Unlocker/SERP API)

You can target the entire European Union region in the same manner as "Country" above by adding "eu" after "country" in your request: -country-eu

Requests sent using -country-eu, will use IPs from one of the countries below which are included automatically within "eu":


Note: The allocation of a country within the EU is random.


In order to target a specific city you will need to use a Shared (pay-per-IP) or Dedicated proxy network.

When configuring your proxy zone, after selecting your preferred country, you can add a city, to further specify your geotargeting

Once you click on 'Add city' you will be displayed the available cities to target, for the selected country. In order to check the number of available IPs for a specific geolocation.

Once configured, you'll be able to send requests from the selected city, using the following syntax

curl --proxy --proxy-user brd-customer-<CUSTOMER_ID>-zone-<ZONE_NAME>-country-<COUNTRY>-city-<CITY>: <ZONE_PASSWORD> ""

Please note: When selecting a two-word city it'll be written as one word. For example, when targeting Buenos Aires the syntax of the request will be -country-ar-city-buenosaires

To view more geotargeting examples, you may want to review our proxy integration examples page.

View your zone's statistics

There are 2 ways to view your zones statistics:

  • Via the control panel:
    • To see stats across all your zones, go to your dashboard:2023-03-09_13h45_08.png
    • To see stats for a specific zone, go to that zone's settings and click the "statistics" tab:
  • Via API:
    • Please visit this page to see all available API endpoints (in multiple languages) and example responses related to viewing statistics.

Review IPs Allocated to Your Zone

To review the list of IPs allocated to your zone, simply navigate to ‘My proxies page’, click on your Proxy zone, scroll down to the ‘Allocated IPs’ section, then simply click ‘Show allocated IPs’ or ‘Download IPs list'.

View the event log

The event log will show you (at most) the last 200 requests you made with any zone in your account.

In your Bright Data control panel's proxies page:

Go to the "Event Log" tab:


The presented data is:

  • Date: Time and date of the request
  • Zone: What Zone was used for the request
  • Source IP: What IP the request was made from
  • URL: The target site of the request
  • Result: Success or Fail of the request


100% uptime - Assigning automatic IP fallbacks

Datacenter & ISP

The 100% uptime was built to prevent any ‘external’ events from affecting the user. The idea is simple and works the same way for both problems described above – if our system detects a problem, like a connectivity issue or an IP where the GEO isn’t exactly what you asked for when buying that IP, we will automatically route your requests through other IPs which are exactly the same as the original IPs.

At the same time, we wanted to make sure that customers that must use specific IPs will not be affected – so we made some exceptions:

  • If a specific IP is targeted in your request we will not assign a fallback IP to it
  • 100% uptime will not interrupt a live connection. If the fallback is needed, it will play in once the next connection is established

The 100% uptime brings immediate value by providing 100% connectivity and continuous high-performance level, free of charge and without having to make any changes in your code or how you work.

  • To enable 100% uptime:

Navigate to your proxy configuration settings, and under ‘Permissions’ enable ‘100% uptime’

Please note: 100% uptime feature can be turned on or off, via API.

Keep using the same IP in multiple requests

  • This can be done by adding the session flag to the proxy username: br-customer-{YOUR_CUSTOMER_ID}-zone-{YOUR_ZONE}-session-rand39484
    Generate the random number on thread startup, and change it when you want to change the Proxy Peer assigned for the thread's connection.
  • Session ID can be any random string/counter: requests with the same session string will use the same Proxy Peer (as long as possible); requests with different session strings will be assigned different Proxy Peers.
  • To force an IP change, just modify the session ID
  • If an assigned Proxy Peer(exit node IP) becomes unavailable, the Super Proxy will return an error "502 - No peers available" for the first request and then on the second request the super proxy will assign a new peer even if you do not change the session ID.
  • The Session IP is kept persistent for up to 10 minutes of idle time. After 10 minutes with no requests, the IP is released back to the pool.
    To keep this Session/IP for longer, send a tiny keep-alive request every 9 minutes and 30 seconds, to prevent this session from becoming idle for over 10 minutes.
    This request may be anything small, such as /favicon.ico, or even a request that returns 404 (as long as the web server does not disconnect the socket due to this request).
  • If you have multiple Clients and would like to ignore your Clients source IP (which is used together with your session ID to create a session), then you want to use a global session then add glob_ as a prefix to your session:
    Full request example:

Generate the random number on thread startup, and change it when you want to change the Proxy Peer assigned for the thread's connection.

Set limits to bandwidth usage

By default, all proxy zones have unlimited usage, and you can set a limit by one of 4 parameters:

  • $/day
  • $/month
  • bytes/day
  • bytes/month

To set this limit on one of your zones, from Bright Data's 'My proxies page'

  1. Go to any of your zone's settings by clicking on that zone.
  2. Go to the "Access parameters" tab.
  3. Scroll down to "Limit", the default value is "unlimited"
  4. Click the "edit" button
  5. Enable the "spend limit" option.
  6. Set the parameters you wish to work with and click "update"
  7. You'll see the change back in the "Limit" section and the proxies page, in the "Usage/Spend Limit" column.

Whitelist/blacklist IPs and domains

To add IPs to a zone's blacklist/whitelist, there are 2 ways:

  • Important tips re whitelist:
    • IPs that should be whitelisted are your machine's IPs that you'll be sending requests with, not the proxy IPs in your zones.
    • We strongly recommend whitelisting your IPs wherever possible, since when the whitelist is empty, you run the risk of getting your non-whitelisted IPs temporarily blocked in the case where our automatic security blocking system detects any irregular activity. See more info within this video.
    • There is no limit on how many IPs/domains you can add to the whitelist and we also support ranges of IPs.

      Example for adding domains:
    • Example for adding IPs:


Supported Ports & Protocols

Ports 80 and 443 are available by default, supporting HTTP and HTTPS protocols.
The below table shows supported protocols by port:

Port Protocol


Bright Data can support additional ports by request. Every request to support a new port will be followed by a dedicated and additional compliance process with the Bright Data compliance team.
Examples of ports that require Bright Data compliance review before activation:

Port Protocol
8443 HTTP
8243 HTTPS

To make a request to add a port permission to your zone:

  • Go to your zone's settings (it will open on the "configuration" tab by default, if not, please click it)
  • Scroll down to "advanced options" and click it
  • Enable "ports"
  • Input the port numbers you would like to get approved
  • Fill out the form and wait for our compliance team to contact you and approve the request


Refresh IPs Allocated to Your Zone

If you've selected 'Pay per IP' shared, or a dedicated IP type in your zone configuration, you'll be allocated a fixed IP address. From time to time, depending on your use case, you may need to refresh these IP addresses.

In order to refresh IPs allocated to your zone, navigate to your selected zone, under 'Allocated IPs' click on 'Show allocated IPs', check the box of the IP or gIP you wish to refresh and click 'Refresh'

Please note: Refreshing an IP or gIP will result in an extra charge.

Alternatively, you can use API to refresh your dedicated Residential IPs or your Datacenter/ISP IPs


Was this article helpful?