ProxyAPI / Documentation

One connection. Full control.

Connect the proxy, control routing per connection, and manage keys, usage, billing, and health from the same API.

Make the first request → View code examples

quickstart.sh

# TLS to the proxy endpoint too
proxy='https://sk_live_KEY:@proxy.proxyapi.se:443'
curl -x "$proxy" https://httpbin.org/ip

{ "origin": "185.x.x.x" }

CONNECTSmart routingREST API

Control API: https://api.proxyapi.se · Authorization: Bearer <API_KEY>

Quick start — Proxy connection

Use the API key as the proxy username. For the control API, use the same key as a Bearer token against https://api.proxyapi.se.

Host	proxy.proxyapi.se
Port (HTTPS to proxy)	443 — recommended
Port (HTTP to proxy)	8080 — trusted networks only
Username	your-api-key
Password	(leave empty)

curl -x https://sk_live_abc123:@proxy.proxyapi.se:443 https://httpbin.org/ip

import requests
proxies = {"http": "https://sk_live_abc123:@proxy.proxyapi.se:443",
           "https": "https://sk_live_abc123:@proxy.proxyapi.se:443"}
print(requests.get("https://httpbin.org/ip", proxies=proxies).json())

curl -H 'Authorization: Bearer sk_live_abc123' \
  https://api.proxyapi.se/v1/customer/usage

Per-request targeting

Choose proxy type, country, session, or provider per request by adding modifiers to the proxy username. Your base API key is followed by -key-value pairs. Modifiers only affect the single connection and do not override your persistent preferences.

# ISP proxies in Sweden only
curl -x 'https://sk_live_abc123-country-se-type-isp:@proxy.proxyapi.se:443' https://ifconfig.me

# Sticky session (same exit IP for ~10 min)
curl -x 'https://sk_live_abc123-session-job42-type-residential:@proxy.proxyapi.se:443' https://...

# Force or exclude a provider
curl -x 'https://sk_live_abc123-provider-iproyal:@proxy.proxyapi.se:443' https://...
curl -x 'https://sk_live_abc123-provider-!agent:@proxy.proxyapi.se:443' https://...

Modifier	Values	Example
-type-	`isp`, `residential`, `datacenter`, `mobile`, `agent`	-type-residential
-country-	Two lowercase ISO-3166-1 letters	-country-se
-session-	4–32 lowercase letters/digits. Same ID → same exit IP (10 min default).	-session-abc42
-ttl-	Session lifetime, up to 60 minutes.	-ttl-30m
-provider-	Only proxies from this provider.	-provider-iproyal
-provider-!	Any provider except this one.	-provider-!agent

Modifiers can be combined in any order; the username is parsed right-to-left until the first non-modifier token. Everything to the left of that is the API key.

Bearer auth works the same way: Proxy-Authorization: Bearer sk_live_abc123-type-isp.

API Keys

GET/v1/customer/keys

List all API keys.

{ "keys": [{ "id": "uuid", "name": "prod", "prefix": "sk_live_abc",
    "created_at": "...", "last_used_at": null, "revoked_at": null }] }

POST/v1/customer/keys

Create a new key. Body: {"name": "prod"}

{ "raw": "sk_live_abc123...", "prefix": "sk_live_abc", "name": "prod" }

The key (raw) is only shown once.

DELETE/v1/customer/keys/:id

Revoke an API key. Cannot be undone.

Usage data

GET/v1/customer/usage?from=YYYY-MM-DD&to=YYYY-MM-DD&source=all

Daily usage data. source can be all, proxy, or validator.

{ "source": "all", "days": [{ "day": "2026-04-13", "gb_used": 0.023, "requests": 1420,
    "bytes_in": 12345678, "bytes_out": 98765432 }],
  "total_gb": 0.456, "total_requests": 28400 }

GET/v1/customer/usage/source-summary?from=...&to=...

Breakdown between regular proxy traffic and validator traffic.

{ "validator": { "requests": 24, "gb": 0.02 },
  "proxy": { "requests": 28400, "gb": 12.32 } }

GET/v1/customer/usage/hosts

The top 20 destination hosts in the current month.

{ "hosts": [{ "sni_host": "example.com", "gb_used": 0.12, "requests": 5400 }] }

Billing & plans

GET/v1/customer/billing

Current plan, cycle status, credit balance. Monitor your quota programmatically.

{ "plan": { "code": "starter", "monthly_price_ore": 9900, "included_gb": 25,
    "overage_ore_per_gb": 500 },
  "current_cycle": { "gb_used": 12.34, "gb_remaining": 12.66,
    "gb_overage": 0, "estimated_overage_cost_ore": 0 },
  "credit_balance_ore": 0, "allow_overage": true, "has_subscription": true }

GET/v1/customer/billing/plans

List public plans with price, included traffic, rate limit, and concurrent sessions.

POST /v1/customer/billing/checkout · /upgrade · /cancel · GET /portal

Manage the subscription. Checkout accepts {"plan":"starter"}, upgrade accepts a new plan, cancel accepts optional immediately, and portal returns portal_url.

Plan values: starter, pro, or business.

GET/v1/customer/billing/invoices

Invoice history.

{ "invoices": [{ "id": "uuid", "cycle_start": "2026-03-01",
    "cycle_end": "2026-03-31", "gb_used": 18.5, "gb_included": 25,
    "gb_overage": 0, "overage_cost_ore": 0 }] }

Proxy preferences

Set your preferred proxy type. The system prioritizes your choice but automatically falls back to other available proxies if the preferred type is unavailable.

GET/v1/customer/preferences

Get current preferences.

{ "proxy_type": "auto", "sticky_sessions": false }

PATCH/v1/customer/preferences

Update preferences.

{ "proxy_type": "residential" }

proxy_type	`auto`, `datacenter`, `residential`, `isp`, `mobile`
sticky_sessions	Keep same proxy IP within a session (`true/false`)

auto (default) — the system makes a weighted choice using success rate, latency, load, and the administrative weight. Recommended for most use cases.

Proxy exclusions

Opt out of individual proxies that don't work for your target. The selector skips them for your customer identity only — they stay available for everyone else. The system also auto-weights down proxies with low success rates (visible in the dashboard), so manual exclusion is mainly needed when a proxy is systematically blocked by your specific destination.

GET/v1/customer/proxy-exclusions

List your excluded proxies.

{ "exclusions": [{ "proxyId": "uuid", "proxyHost": "1.2.3.4", "proxyPort": 12323,
    "proxyType": "datacenter", "reason": "blocked by target",
    "createdAt": "2026-04-21T08:00:00Z" }] }

POST/v1/customer/proxy-exclusions

Exclude a proxy. Takes effect within ~10s (selector refresh cycle).

{ "proxy_id": "uuid", "reason": "403 on target" }

DELETE/v1/customer/proxy-exclusions/:proxyId

Restore a previously excluded proxy.

Health validators

Automated HTTP checks through your proxies. Reports status, response time and observed IP.

GET/v1/customer/validators

List all validators.

POST/v1/customer/validators

Create a validator.

{ "code": "check-httpbin", "url": "https://httpbin.org/ip",
  "expected_status": 200, "run_interval_sec": 300 }

code	Unique identifier (required)
url	URL to check (required)
expected_status	Expected HTTP status (default 200)
run_interval_sec	Interval in seconds (default 300)

PATCH/v1/customer/validators/:id

Update code, url, expected_status, run_interval_sec, or enabled.

GET/v1/customer/validators/:id/results

The latest 100 results.

{ "results": [{ "id": "uuid", "startedAt": "2026-04-13T12:00:00Z",
    "responseMs": 234, "statusCode": 200, "success": true,
    "observedIp": "185.x.x.x", "errorMessage": null }] }

DELETE/v1/customer/validators/:id

Delete validator and all results.

Error codes

401

Unauthorized

API key missing or invalid.

403

Forbidden

Not authorized for this resource.

404

Not Found

Resource does not exist.

407

Proxy Auth Required

Proxy key missing (proxy gateway).

429

Too Many Requests

Rate limit or quota exceeded.

500

Internal Error

Server error. Try again.

503

Unavailable

An external billing function is not configured or is temporarily unavailable.

Next steps

Monitor usage in the dashboard
Build integrations with the usage and billing API
Set up health validators for proxy monitoring
Questions? hello@proxyapi.se