CUSTOMER API DOCUMENTATION
From API key to usable proxies.
Apply a two-port configuration, check the result, then download the addresses your application will use.
ProxySight docsUpdated On this page
1. Get your account API key↗
Create an API key in the dashboard and set PS_API_KEY in your environment. Python examples need requests; Java examples use Java 17; cURL examples use a POSIX shell.
Confirm active access with GET /customer/account. Read GET /customer/locations to choose a combination with at least two available ports. PS_API_BASE_URL can override the default base URL in each example.
2. Generate two rotating endpoints↗
PUT
Applies Every request, World Pool, HTTP and proxy credentials; returns the saved configuration and two endpoints./api/v1.0/customer/proxies/configurationAuthorization: Bearer <PS_API_KEY>120 / minute overall · configuration: 20 / 5 minutes
Send the complete configuration. Use the smallest list your first check needs. The call can take longer while the account is synchronized across the gateways.
application/json
Example response
{
"gatewayReady": true,
"synced": true,
"access": true,
"allowance": {
"ports": 500,
"threads": 500,
"trial": false
},
"settings": {
"mode": "request",
"protocol": "http",
"authentication": "credentials",
"country": "world",
"count": 2,
"interval": 30
},
"whitelist": [],
"credentials": {
"username": "ps_user_7_example",
"password": "your-proxy-password"
},
"endpoints": [
{
"id": 1,
"host": "192.0.2.10",
"port": 40300,
"country": "world",
"pool": "world",
"mode": "request",
"interval": 30
},
{
"id": 2,
"host": "192.0.2.11",
"port": 40301,
"country": "world",
"pool": "world",
"mode": "request",
"interval": 30
}
],
"distribution": {
"192.0.2.10": 1,
"192.0.2.11": 1
},
"user": {
"id": 7,
"email": "[email protected]",
"username": "casey",
"role": "customer",
"emailVerified": true,
"status": "ACTIVE",
"createdAt": "2026-10-20T10:00:00+00:00",
"providers": [],
"canEditCredentials": true,
"tier": "premium",
"trial": {
"active": false,
"used": true,
"limitBytes": 1000000000,
"usedBytes": 1000000000,
"requests": 2500
},
"plan": {
"id": "growth",
"autoRenew": true,
"paymentProvider": "stripe",
"amountCents": 6000,
"subscriptionId": "sub_example",
"name": "Growth",
"status": "active",
"concurrency": 500,
"ports": 500,
"billingPeriod": "monthly",
"expiresAt": "2026-11-24T10:00:00+00:00"
}
}
}JSON request body
{
"mode": "request",
"protocol": "http",
"authentication": "credentials",
"country": "world",
"count": 2,
"interval": 30
}request.pyPython
Before you run
Python 3.10+ · pip install requests · Set PS_API_KEY in your environment.import os
import requests
base = os.getenv("PS_API_BASE_URL", "https://proxysight.com/api/v1.0").rstrip("/")
key = os.environ["PS_API_KEY"]
response = requests.request(
"PUT",
f"{base}/customer/proxies/configuration",
headers={"Authorization": f"Bearer {key}"},
json={"mode": "request", "protocol": "http", "authentication": "credentials", "country": "world", "count": 2, "interval": 30},
timeout=120,
)
response.raise_for_status()
print(response.json())
Request parameters 8 inputs +
| Parameter | Where | Value |
|---|---|---|
modestring · required | body | request = Every request; timed = Sticky session with an interval; static = Keep the same IP. |
protocolstring · required | body | http or socks5. HTTP supports HTTPS destinations through CONNECT. |
authenticationstring · required | body | credentials or ip. Add a source address before selecting ip. |
countrystring · required | body | request/timed: world, eu or us. static: world, eu or an available lowercase country code. |
countinteger · required | body | 1–2,000, further limited by your plan and the matching available inventory. |
intervalinteger · optional | body | 10, 30, 60, 300, 600, 900, 1800, 3600, 7200, 21600, 43200 or 86400 seconds; default 30. Only timed mode uses it, but the value must always be valid. |
expectedRevisionstring · optional | body | The active 24-character lowercase hex revision from GET /customer/proxies. Stale versions return 409. |
requestIdstring · optional | body | A unique 32-character lowercase hex request reference. Reuse it with exactly the same body after a timeout. |
Response fields 7 fields +
| Field | Meaning |
|---|---|
access / allowanceboolean / object | null | Whether the account can use proxies, with its ports, threads and trial flag. |
gatewayReady / syncedboolean | Gateway access is configured and the saved settings have reached all three gateways. |
settingsobject | null | The active mode, protocol, authentication, location, count and interval. |
credentialsobject | Separate proxy username and password. These are private and are not your API key. |
endpoints[]array | Gateway host/port entries to use in your client. They are not a list of dedicated exit IPs. |
distributionobject | How many returned endpoints belong to each gateway host. |
whitelist / userarray / object | Authorized source addresses and the public account/plan summary. |
Errors & recovery 7 cases +
| HTTP | What happened | What to do |
|---|---|---|
401 | The API key is missing, revoked, or its account is unavailable. | Use the current Bearer key from Settings → API key. |
429 | The account request limit was reached. | Wait for the Retry-After header before retrying. |
500 | The request could not be completed. | Retry reads with backoff. After a write, read the saved state before sending it again. |
403 | No active trial or paid proxy access. | Read /customer/account and activate a plan if needed. |
409 | Another account configuration update is still running. | Wait, then read /customer/proxies before changing it again. |
422 | A setting, source IP, inventory selection or count is invalid. | Use the returned field error and the location capacity response. |
503 | Gateway synchronization could not finish. | The desired settings are retained. Read the saved state before retrying. |
3. Download and use the result↗
| Check in the response | What to do |
|---|---|
| access: true; synced: true | The saved account configuration is ready. |
| endpoints[] + credentials | Use each returned host and port with the separate proxy username/password. |
| GET /customer/proxies/export?format=uri | Save a complete connection URI per line. Treat this file as a secret. |
Common questions
Does my API key authenticate proxy connections?
No. It controls the customer API. Proxy traffic uses the generated proxy credentials or an authorized source IPv4 address.
Further reading
Requests: proxy configuration (opens in a new tab)Java 17 HTTP client configuration (opens in a new tab)cURL command reference (opens in a new tab)Need help with this guide?Send us your question