API Reference

Everything you need to integrate ProxySave into your application.

Authentication

All requests require authentication via two headers. Your username and API key are provided when you create an account.

Header	Description
`X-Openproxy-Username`required	Your ProxySave username.
`X-Openproxy-Password`required	Your API key (starts with ps_live_ or ps_test_).

Request format

Send requests to the /fetch endpoint. The target URL and routing behavior are controlled via headers.

endpoint

POST https://api.proxysave.com/fetch

Request headers

Header	Description
`url`required	The target URL to fetch through the proxy.
`provider`	Routing strategy or specific provider name. Options: `cheapest` (default), `fastest`, or a specific provider name (e.g., `brightdata`).
`label`	Tag for per-workload learning. Requests with the same label build a shared performance profile. Use descriptive names like product-scraper or price-monitor.
`max-price-per-gb`	Maximum acceptable cost in USD per GB. Providers exceeding this are excluded from routing. Example: 3.00
`max-time-ms`	Maximum acceptable response time in milliseconds. Providers historically slower than this for your workload are deprioritized. Example: 2000

Full example

terminal

curl -X POST https://api.proxysave.com/fetch \
  -H "X-Openproxy-Username: acme-corp" \
  -H "X-Openproxy-Password: ps_live_abc123" \
  -H "url: https://api.example.com/products" \
  -H "provider: cheapest" \
  -H "max-price-per-gb: 3.00" \
  -H "max-time-ms: 2000" \
  -H "label: product-catalog"

Response

The response body is the proxied content from the target URL, returned exactly as the upstream server sent it. ProxySave adds metadata headers to help you monitor routing and costs:

Header	Description
`X-ProxySave-Provider`	The provider that served this request.
`X-ProxySave-Cost-Per-GB`	Effective cost in USD per GB for this request.
`X-ProxySave-Latency-Ms`	Total response time in milliseconds.
`X-ProxySave-Retries`	Number of automatic retries before a successful response (0 = first attempt succeeded).

Error codes

When a request fails, ProxySave returns a JSON error body with a machine-readable code and a human-readable message.

error response

{
  "error": "NO_PROVIDERS_AVAILABLE",
  "message": "No providers meet your constraints (max $1.00/GB, <500ms).",
  "status": 503
}

Code	Status	Description
`AUTH_FAILED`	401	Missing or invalid username/API key.
`MISSING_URL`	400	The url header is missing from the request.
`INVALID_CONSTRAINTS`	400	max-price-per-gb or max-time-ms has an invalid value.
`NO_PROVIDERS_AVAILABLE`	503	No providers meet your cost and latency constraints. Relax your limits or add more provider keys.
`ALL_PROVIDERS_FAILED`	502	All qualifying providers were tried but returned errors. The last error is included in the response.
`PROVIDER_NOT_FOUND`	404	The specified provider name doesn't exist or isn't configured for your account.
`RATE_LIMITED`	429	Too many requests. Back off and retry with exponential delay.