CUSTOMER API DOCUMENTATION
Get endpoints for the protocol you use.
Select the protocol in the configuration body. The API response remains JSON; the generated connection protocol changes.
ProxySight docsUpdated On this page
HTTP or SOCKS5?↗
Use the exact host and port returned for the chosen protocol. Changing a scheme in an old connection string does not select the matching gateway listener.
| Configuration | Exported URI | Connection use |
|---|---|---|
| protocol: http | http://… | HTTP clients and HTTPS destinations through a CONNECT tunnel. |
| protocol: socks5 | socks5://… | SOCKS5-capable applications. Configure remote DNS in your client when needed. |
Generate SOCKS5 endpoints↗
PUT
Applies a SOCKS5 selection and returns the matching endpoints and proxy credentials./api/v1.0/customer/proxies/configurationAuthorization: Bearer <PS_API_KEY>120 / minute overall · configuration: 20 / 5 minutes
The Python, Java and cURL examples call the customer API over HTTPS. Your application then connects through the returned SOCKS5 endpoints using a SOCKS5-capable client.
application/json
Example response
{
"gatewayReady": true,
"synced": true,
"access": true,
"allowance": {
"ports": 500,
"threads": 500,
"trial": false
},
"settings": {
"mode": "request",
"protocol": "socks5",
"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": "socks5",
"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": "socks5", "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. |
Use the generated values in your application↗
- HTTP: use the generated http:// proxy URL, including for HTTPS targets. The target’s HTTPS connection uses CONNECT.
- SOCKS5: use a client with SOCKS support. Python Requests needs requests[socks]; cURL can use socks5h:// for proxy-side DNS.
- Java 17’s standard HttpClient supports HTTP proxy configuration. Use an appropriate SOCKS-capable client for SOCKS5 traffic.
Common questions
Does protocol: http prevent HTTPS requests?
No. The HTTP proxy handles HTTPS destinations through CONNECT. Use the returned HTTP listener rather than substituting an unconfigured TLS-to-proxy scheme.
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)Java 17 networking and proxy authentication settings (opens in a new tab)Need help with this guide?Send us your question