Proxies
Attach an http, https, or socks5 proxy to a profile, override it per launch, manage a proxy library, and store provider credentials in a vault.
Proxy formats
A proxy is a URL in scheme://user:pass@host:port form. The user:pass@ segment is optional, so omit it for an open proxy. These schemes are accepted directly as a profile or launch proxy.
| Scheme | Example |
|---|---|
| http | http://user:pass@host:8000 |
| https | https://user:pass@host:8443 |
| socks5 | socks5://user:pass@host:1080 |
| socks4 | socks4://host:1080 |
The proxy library additionally recognizes the ssh and tor proxy types for entries you save there.
Per profile and per launch
A proxy can be bound to a profile so every launch uses it, or passed once in the launch body to override the profile for a single launch. A per launch override is applied to that launch only and is never written back to the saved profile.
| Where | Field | Scope |
|---|---|---|
| On the profile | proxy or proxy_url | Every launch of the profile |
| Library reference | proxy_library_id | Every launch, from a shared library entry |
| Vault binding | proxy_provider_credential_id | Every launch, synthesized from provider credentials |
| Per launch override | proxy in the launch body | This launch only, never saved |
{ "proxy": "socks5://user:pass@gateway.example.com:1080" }proxy override is applied as given and skips the startup leak check. For the built in leak guard that aborts a launch when the egress IP equals your local IP, bind the proxy to the profile instead.Proxy library
Save reusable proxies in the library, then reference them from profiles by id. You can check or rotate an entry without relaunching a profile.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/proxies | List saved proxies |
| POST | /api/proxies | Add a proxy |
| POST | /api/proxies/bulk-add | Add many proxies from a list of URLs |
| PUT | /api/proxies/{id} | Update a saved proxy |
| DELETE | /api/proxies/{id} | Remove a saved proxy |
| POST | /api/proxies/{id}/check | Test connectivity and report the egress |
| POST | /api/proxies/{id}/rotate | Rotate a rotating endpoint |
Add a proxy with the following fields. Only url is required.
| Field | Type | Description |
|---|---|---|
| url | string | Proxy URL in scheme://user:pass@host:port form. Required. |
| label | string | Friendly name for the entry. |
| proxy_type | "http" | "https" | "socks4" | "socks5" | "ssh" | "tor" | Connection type. Inferred from the URL when omitted. |
| change_ip_url | string | URL fetched on launch to rotate the exit IP. |
| provider | string | Free text provider tag, for example iproyal. |
Provider vault
For commercial networks, store account credentials once in the vault and bind them to profiles. The vault synthesizes the connection details from your account credentials, so the raw password never has to live on each profile. The password is write only and is never returned in a response.
| Method | Path | Purpose |
|---|---|---|
| GET | /api/proxy-credentials | List saved provider credentials |
| POST | /api/proxy-credentials | Add a provider credential |
| PATCH | /api/proxy-credentials/{id} | Update a credential |
| DELETE | /api/proxy-credentials/{id} | Remove a credential |
| POST | /api/proxy-credentials/{id}/preview | Preview, and optionally test, a synthesized endpoint |
Supported providers. Pass the catalog key as provider. Each takes a username and password, plus a country and session mode you choose per profile.
| Key | Provider |
|---|---|
| brightdata | Bright Data |
| oxylabs | Oxylabs |
| decodo | Decodo (formerly Smartproxy) |
| iproyal | IPRoyal |
| soax | SOAX |
| netnut | NetNut |
| custom | Custom provider with your own host, port, and credential templates |
Bind a credential to a profile with these fields. The session mode controls whether the exit IP rotates per request or stays pinned for the profile.
| Field | Type | Description |
|---|---|---|
| proxy_provider_credential_id | string | Vault credential the profile uses. |
| proxy_provider_country | string | Per profile country override, for example de. |
| proxy_provider_session | "rotating" | "sticky" | rotating gives a new exit IP per request. sticky pins one exit IP to the profile via a session token. |