Proxies

Browserless offers a built-in residential proxy. To use it, add the proxy parameters to your REST API request query strings.

REST APIs

All of our REST-APIs function the same for proxying: simply add the proxy parameters you care about to the requests' query-string parameters, and you're all done. No need for credentials or otherwise.

Available proxy parameters:

• proxy=residential - Enables residential proxy routing
• proxyCountry=us - Routes through a specific country (ISO 3166 country codes)
• proxyCity=chicago - Routes through a specific city within the selected country
• proxySticky=true - Maintains the same proxy IP across the session

City-Level Proxying

City-level proxying requires a Scale plan (500k+ units). Plans under 500k units will receive a 401 error.

To get a list of available cities, use the following endpoints:

• All supported cities: https://production-sfo.browserless.io/proxy/cities?token=YOUR_TOKEN
• Cities for a specific country: https://production-sfo.browserless.io/proxy/cities?country=US&token=YOUR_TOKEN

Here's an examples of collecting content, pdf and screenshot from a United States Proxy:

Content

cURL

curl --request POST \
  --url "https://production-sfo.browserless.io/content?token=YOUR_API_TOKEN_HERE&proxyCountry=us&proxy=residential" \
  --header "Content-Type: application/json" \
  --data "{
    \"url\": \"https://ip-api.com\"
  }" \
  --output "ipinfo.html"

Javascript

import fetch from 'node-fetch';
import { writeFile } from 'fs/promises';

const TOKEN = "YOUR_API_TOKEN_HERE";

const url = `https://production-sfo.browserless.io/content?token=${TOKEN}&proxyCountry=us&proxy=residential`;
const headers = {
    "Content-Type": "application/json"
};
const data = {
    url: "https://ip-api.com"
};

const fetchContent = async () => {
    const response = await fetch(url, {
        method: 'POST',
        headers: headers,
        body: JSON.stringify(data)
    });

    const html = await response.text();
    await writeFile("ipinfo.html", html);
    console.log("HTML content saved as ipinfo.html");
};

fetchContent();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/content?token={TOKEN}&proxyCountry=us&proxy=residential"
headers = {
    "Content-Type": "application/json"
}
data = {
    "url": "https://ip-api.com"
}

response = requests.post(url, headers=headers, json=data)

with open("ipinfo.html", "wb") as f:
    f.write(response.content)

print("HTML content saved as ipinfo.html")

Java

import java.io.*;
import java.net.http.*;
import java.net.URI;

public class FetchHTML {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/content?token=" + TOKEN + "&proxyCountry=us&proxy=residential";

        HttpClient client = HttpClient.newHttpClient();

        String jsonData = """
            {
                "url": "https://ip-api.com"
            }
        """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<InputStream> response = client.send(request, HttpResponse.BodyHandlers.ofInputStream());
            try (FileOutputStream fos = new FileOutputStream("ipinfo.html")) {
                response.body().transferTo(fos);
                System.out.println("HTML content saved to ipinfo.html");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/content?token={TOKEN}&proxyCountry=us&proxy=residential";

        var payload = new {
            url = "https://ip-api.com"
        };

        var jsonContent = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        using var httpClient = new HttpClient();
        try {
            var response = await httpClient.PostAsync(url, jsonContent);
            response.EnsureSuccessStatusCode();

            var contentStream = await response.Content.ReadAsStreamAsync();
            using (var fileStream = new FileStream("ipinfo.html", FileMode.Create, FileAccess.Write, FileShare.None)) {
                await contentStream.CopyToAsync(fileStream);
                Console.WriteLine("HTML content saved to ipinfo.html");
            }
        } catch (Exception e) {
            Console.WriteLine("Error: " + e.Message);
        }
    }
}

PDF

cURL

curl --request POST \
  --url "https://production-sfo.browserless.io/pdf?token=YOUR_API_TOKEN_HERE&proxyCountry=us&proxy=residential" \
  --header "Content-Type: application/json" \
  --data "{
    \"url\": \"https://ip-api.com\"
  }" \
  --output "ipinfo.pdf"

Javascript

import fetch from 'node-fetch';
import { writeFile } from 'fs/promises';

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/pdf?token=${TOKEN}&proxyCountry=us&proxy=residential`;
const headers = {
  "Content-Type": "application/json"
};
const data = {
  url: "https://ip-api.com"
};

const fetchPDF = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const pdfBuffer = await response.arrayBuffer();
  await writeFile("ipinfo.pdf", Buffer.from(pdfBuffer));
  console.log("PDF content saved as ipinfo.pdf");
};

fetchPDF();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/pdf?token={TOKEN}&proxyCountry=us&proxy=residential"
headers = {
    "Content-Type": "application/json"
}
data = {
    "url": "https://ip-api.com"
}

response = requests.post(url, headers=headers, json=data)

with open("ipinfo.pdf", "wb") as f:
    f.write(response.content)

print("PDF content saved as ipinfo.pdf")

Java

import java.io.*;
import java.net.http.*;
import java.net.URI;

public class FetchPDF {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/pdf?token=" + TOKEN + "&proxyCountry=us&proxy=residential";

        HttpClient client = HttpClient.newHttpClient();

        String jsonData = """
            {
                "url": "https://ip-api.com"
            }
        """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<InputStream> response = client.send(request, HttpResponse.BodyHandlers.ofInputStream());
            try (FileOutputStream fos = new FileOutputStream("ipinfo.pdf")) {
                response.body().transferTo(fos);
                System.out.println("PDF saved as ipinfo.pdf");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/pdf?token={TOKEN}&proxyCountry=us&proxy=residential";

        var payload = new {
            url = "https://ip-api.com"
        };

        var jsonContent = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        using var httpClient = new HttpClient();
        try {
            var response = await httpClient.PostAsync(url, jsonContent);
            response.EnsureSuccessStatusCode();

            var contentStream = await response.Content.ReadAsStreamAsync();
            using (var fileStream = new FileStream("ipinfo.pdf", FileMode.Create, FileAccess.Write, FileShare.None)) {
                await contentStream.CopyToAsync(fileStream);
                Console.WriteLine("PDF saved as ipinfo.pdf");
            }
        } catch (Exception e) {
            Console.WriteLine("Error: " + e.Message);
        }
    }
}

Screenshot

cURL

curl --request POST \
  --url "https://production-sfo.browserless.io/screenshot?token=YOUR_API_TOKEN_HERE&proxyCountry=us&proxy=residential" \
  --header "Content-Type: application/json" \
  --data "{
    \"url\": \"https://ip-api.com\"
  }" \
  --output "ipinfo.png"

Javascript

import fetch from 'node-fetch';
import { writeFile } from 'fs/promises';

const TOKEN = "YOUR_API_TOKEN_HERE";
const url = `https://production-sfo.browserless.io/screenshot?token=${TOKEN}&proxyCountry=us&proxy=residential`;
const headers = {
  "Content-Type": "application/json"
};
const data = {
  url: "https://ip-api.com"
};

const fetchScreenshot = async () => {
  const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
  });

  const imageBuffer = await response.arrayBuffer();
  await writeFile("ipinfo.png", Buffer.from(imageBuffer));
  console.log("Screenshot saved as ipinfo.png");
};

fetchScreenshot();

Python

import requests

TOKEN = "YOUR_API_TOKEN_HERE"
url = f"https://production-sfo.browserless.io/screenshot?token={TOKEN}&proxyCountry=us&proxy=residential"
headers = {
    "Content-Type": "application/json"
}
data = {
    "url": "https://ip-api.com"
}

response = requests.post(url, headers=headers, json=data)

with open("ipinfo.png", "wb") as f:
    f.write(response.content)

print("Screenshot saved as ipinfo.png")

Java

import java.io.*;
import java.net.http.*;
import java.net.URI;

public class FetchScreenshot {
    public static void main(String[] args) {
        String TOKEN = "YOUR_API_TOKEN_HERE";
        String url = "https://production-sfo.browserless.io/screenshot?token=" + TOKEN + "&proxyCountry=us&proxy=residential";

        HttpClient client = HttpClient.newHttpClient();

        String jsonData = """
            {
                "url": "https://ip-api.com"
            }
        """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(jsonData))
            .build();

        try {
            HttpResponse<InputStream> response = client.send(request, HttpResponse.BodyHandlers.ofInputStream());
            try (FileOutputStream fos = new FileOutputStream("ipinfo.png")) {
                response.body().transferTo(fos);
                System.out.println("Screenshot saved as ipinfo.png");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

C#

using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program {
    static async Task Main(string[] args) {
        string TOKEN = "YOUR_API_TOKEN_HERE";
        string url = $"https://production-sfo.browserless.io/screenshot?token={TOKEN}&proxyCountry=us&proxy=residential";

        var payload = new {
            url = "https://ip-api.com"
        };

        var jsonContent = new StringContent(JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        using var httpClient = new HttpClient();
        try {
            var response = await httpClient.PostAsync(url, jsonContent);
            response.EnsureSuccessStatusCode();

            var contentStream = await response.Content.ReadAsStreamAsync();
            using (var fileStream = new FileStream("ipinfo.png", FileMode.Create, FileAccess.Write, FileShare.None)) {
                await contentStream.CopyToAsync(fileStream);
                Console.WriteLine("Screenshot saved as ipinfo.png");
            }
        } catch (Exception e) {
            Console.WriteLine("Error: " + e.Message);
        }
    }
}