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:
Authorization: Bearer YOUR_API_KEY
Query Parameter Authentication
Alternatively, you can pass your API key as a query parameter:
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
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
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 -X GET "https://api.proxyvault.io/v1/list/json?protocol=http&country=US&limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response (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 -X GET "https://api.proxyvault.io/v1/random/json?protocol=socks5" \
-H "Authorization: Bearer YOUR_API_KEY"
Example Response (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 -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
{
"status": "error",
"error": {
"code": 401,
"message": "Invalid API key"
}
}
Code Examples
JavaScript (Fetch API)
// 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)
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
// 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');
?>