Developer Center

API Documentation

Complete reference for the ProxyVault API. Use our powerful and reliable proxy API to access fresh, verified proxies for your applications.

Quick Integration

Simple REST API with examples in multiple languages for fast implementation.

Advanced Filtering

Filter proxies by country, protocol, anonymity level, and response time.

Multiple Formats

Get proxies in JSON, plaintext, or CSV format based on your needs.

Authentication

All API requests require authentication using an API key. You can find your API key in your account dashboard.

Header Authentication (Recommended)

Include your API key in the Authorization header:

http
Authorization: Bearer YOUR_API_KEY

Query Parameter Authentication

Alternatively, you can pass your API key as a query parameter:

http
https://api.proxyvault.io/v1/list?api_key=YOUR_API_KEY

Always keep your API key secure and never share it publicly.

Response Formats

The API supports multiple response formats. Specify your preferred format in the URL path or as a query parameter.

Available Formats

  • JSON - Default format for structured data
  • TXT - Plain text, one proxy per line in IP:PORT format
  • CSV - Comma-separated values with headers

Specifying Format in URL Path

url
https://api.proxyvault.io/v1/list/json
https://api.proxyvault.io/v1/list/txt
https://api.proxyvault.io/v1/list/csv

Specifying Format as Query Parameter

url
https://api.proxyvault.io/v1/list?format=json
https://api.proxyvault.io/v1/list?format=txt
https://api.proxyvault.io/v1/list?format=csv

Endpoints

The API provides three main endpoints for accessing proxies.

GET /list

Returns a list of proxies based on specified filters.

Parameters

Parameter Type Description Default
protocol string Filter by protocol: http, https, socks4, socks5, or all all
country string Filter by two-letter country code (ISO 3166-1 alpha-2) -
anonymity string Filter by anonymity level: transparent, anonymous, elite -
timeout integer Maximum response time in milliseconds 10000
limit integer Maximum number of proxies to return (1-1000) 100
page integer Page number for pagination 1

Example Request

curl
curl -X GET "https://api.proxyvault.io/v1/list/json?protocol=http&country=US&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"

Example Response (JSON)

json
{
  "status": "success",
  "data": {
    "count": 10,
    "total": 245,
    "page": 1,
    "pages": 25,
    "proxies": [
      {
        "ip": "203.0.113.1",
        "port": 8080,
        "protocol": "http",
        "country": "US",
        "anonymity": "elite",
        "last_checked": "2025-04-10T12:42:10Z",
        "response_time": 320
      },
      {
        "ip": "203.0.113.2",
        "port": 3128,
        "protocol": "http",
        "country": "US",
        "anonymity": "anonymous",
        "last_checked": "2025-04-10T12:41:55Z",
        "response_time": 450
      }
      // ... more proxies
    ]
  }
}

GET /random

Returns a single random proxy matching the specified criteria.

Parameters

Parameter Type Description Default
protocol string Filter by protocol: http, https, socks4, socks5, or all all
country string Filter by two-letter country code (ISO 3166-1 alpha-2) -
anonymity string Filter by anonymity level: transparent, anonymous, elite -
timeout integer Maximum response time in milliseconds 10000

Example Request

curl
curl -X GET "https://api.proxyvault.io/v1/random/json?protocol=socks5" \
-H "Authorization: Bearer YOUR_API_KEY"

Example Response (JSON)

json
{
  "status": "success",
  "data": {
    "ip": "203.0.113.15",
    "port": 1080,
    "protocol": "socks5",
    "country": "DE",
    "anonymity": "elite",
    "last_checked": "2025-04-10T12:42:10Z",
    "response_time": 280
  }
}

GET /download

Returns a downloadable file containing proxies based on specified filters. Useful for bulk exporting.

Parameters

Parameter Type Description Default
protocol string Filter by protocol: http, https, socks4, socks5, or all all
country string Filter by two-letter country code (ISO 3166-1 alpha-2) -
anonymity string Filter by anonymity level: transparent, anonymous, elite -
timeout integer Maximum response time in milliseconds 10000
format string File format: json, txt, csv txt

Example Request

curl
curl -X GET "https://api.proxyvault.io/v1/download?protocol=all&country=US&format=csv" \
-H "Authorization: Bearer YOUR_API_KEY" \
-o proxies.csv

The response will be a downloadable file in the specified format.

Rate Limits

API rate limits depend on your subscription plan. The current limits for your account are:

Plan Requests per Day Requests per Minute
Starter 1,000 10
Pro 10,000 50
Elite Unlimited 200

Rate limit headers are included in each response.

Error Handling

The API uses standard HTTP status codes to indicate success or failure of a request.

Common Error Codes

Status Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Missing or invalid API key
403 Forbidden - You don't have permission to access this resource
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error Response Format

json
{
  "status": "error",
  "error": {
    "code": 401,
    "message": "Invalid API key"
  }
}

Code Examples

JavaScript (Fetch API)

javascript
// Get a list of HTTP proxies from the US
const fetchProxies = async () => {
  try {
    const response = await fetch(
      'https://api.proxyvault.io/v1/list/json?protocol=http&country=US&limit=10',
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`HTTP error! Status: ${response.status}`);
    }
    
    const data = await response.json();
    console.log(data);
    return data;
  } catch (error) {
    console.error('Error fetching proxies:', error);
  }
};

fetchProxies();

Python (requests)

python
import requests

# Get a random SOCKS5 proxy
def get_random_proxy():
    url = "https://api.proxyvault.io/v1/random/json"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY"
    }
    params = {
        "protocol": "socks5"
    }
    
    try:
        response = requests.get(url, headers=headers, params=params)
        response.raise_for_status()  # Raise exception for HTTP errors
        
        data = response.json()
        return data
    except requests.exceptions.RequestException as e:
        print(f"Error fetching proxy: {e}")
        return None

# Use the proxy
proxy_data = get_random_proxy()
if proxy_data and proxy_data['status'] == 'success':
    proxy = proxy_data['data']
    proxy_url = f"{proxy['protocol']}://{proxy['ip']}:{proxy['port']}"
    print(f"Using proxy: {proxy_url}")

PHP (cURL)

php
<?php
// Download a list of proxies in CSV format
function downloadProxies($apiKey) {
    $url = "https://api.proxyvault.io/v1/download?format=csv&protocol=http";
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer {$apiKey}"
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        // Save to file
        file_put_contents('proxies.csv', $response);
        echo "Proxies downloaded successfully!";
    } else {
        echo "Error downloading proxies. HTTP code: " . $httpCode;
    }
}

// Usage
downloadProxies('YOUR_API_KEY');
?>