Skip to main content

​
What Proxy Hopper does for your application

Proxy Hopper is a standalone service that sits between your code and the third-party APIs you call. Instead of calling an API directly, you send requests to Proxy Hopper with a header pointing to the real destination. Proxy Hopper picks a proxy IP, makes the HTTPS request, handles retries, and returns the response. Your application code changes are minimal — usually just one extra header.

​
Prerequisites

You need a running Proxy Hopper instance. If one isn’t running yet, see Simple Docker Deployment to spin one up in under five minutes. Ask your administrator for:
  • The Proxy Hopper host and port (e.g. http://proxy-hopper.internal:8080)
  • An API key, if authentication is enabled (see Authenticating)

​
Sending your first request

Add X-Proxy-Hopper-Target to your request headers, set it to the scheme and host of the API you want to call, and send the request to Proxy Hopper instead. 
import requests

session = requests.Session()
session.headers["X-Proxy-Hopper-Target"] = "https://api.example.com"

resp = session.get("http://proxy-hopper:8080/v1/search", params={"q": "test"})
# → Proxy Hopper forwards to https://api.example.com/v1/search?q=test

​
How the target header works

The X-Proxy-Hopper-Target value is the scheme and host of the destination: 
X-Proxy-Hopper-Target: https://api.example.com
You can optionally include a base path. Proxy Hopper prepends it to your request path: 
session.headers["X-Proxy-Hopper-Target"] = "https://api.example.com/v2"
resp = session.get("http://proxy-hopper:8080/search")
# → forwards to https://api.example.com/v2/search
Set up the target (and auth, if needed) on a session once and reuse it: 
import requests

PROXY_HOPPER = "http://proxy-hopper:8080"
TARGET_API = "https://api.example.com"

session = requests.Session()
session.headers["X-Proxy-Hopper-Target"] = TARGET_API
# session.headers["X-Proxy-Hopper-Auth"] = "Bearer ph_mykey"  # if auth is enabled

# All requests go through Proxy Hopper
resp = session.get(f"{PROXY_HOPPER}/v1/search", params={"q": "test"})
resp = session.post(f"{PROXY_HOPPER}/v1/ingest", json={"data": [...]})

​
Control headers

All X-Proxy-Hopper-* headers are stripped before the request reaches the upstream — the API you’re calling never sees them.
HeaderDescription
X-Proxy-Hopper-TargetRequired. Destination scheme + host (+ optional base path)
X-Proxy-Hopper-AuthBearer token — required when auth is enabled
X-Proxy-Hopper-TagOptional label for Prometheus metrics
X-Proxy-Hopper-RetriesOverride retry count for this request only

​
Disabling retries for non-idempotent requests

Proxy Hopper retries failed requests by default. For POST or other non-idempotent calls where a retry would cause a duplicate action, disable retries on that request: 
resp = session.post(
    f"{PROXY_HOPPER}/v1/order",
    json={"item": "widget"},
    headers={"X-Proxy-Hopper-Retries": "0"},
)

​
Tagging requests for visibility

If your team uses Prometheus metrics, tagging requests helps identify which endpoints are hitting rate limits: 
resp = session.get(
    f"{PROXY_HOPPER}/v1/search",
    headers={"X-Proxy-Hopper-Tag": "product-search"},
)

​
Next steps

Sending Requests

Full reference for all control headers and request behaviour.

Authenticating

Add authentication headers when Proxy Hopper requires a token.