Developers

Proxaro API reference

REST over HTTPS, JSON in and JSON out. Every account action you can do from the dashboard is exposed here — query your usage, rotate gateway credentials, manage IP allowlists, list available geos, and receive events via webhooks.

Base URL

https://api.proxaro.io

Content type

application/json

Version

Quick start

Create an API key in Dashboard → API keys, then make your first request:

export PROXARO_API_KEY="proxaro_live_0123456789abcdef0123456789abcdef"

curl https://api.proxaro.io/v1/me \
  -H "Authorization: Bearer $PROXARO_API_KEY"

The API accepts both live (proxaro_live_*) and test (proxaro_test_*) keys. Test keys hit a sandboxed pool with fake usage counters — ideal for CI and local development.

Authentication

Authenticate every request with a bearer token in the Authorization header. Never embed keys in client-side code — they grant full read/write access to your account.

Authorization: Bearer proxaro_live_0123456789abcdef0123456789abcdef

Key format

Keys are prefixed with their environment: proxaro_live_ for production, proxaro_test_ for sandbox. Each key carries scoped permissions — read-only, read/write, or admin — which you pick at creation time.

Errors

The API uses conventional HTTP status codes. Every error response carries the same envelope:

{
  "error": {
    "type": "invalid_request",
    "code": "missing_parameter",
    "message": "The 'country' parameter is required.",
    "param": "country",
    "request_id": "req_01HVQ9M3R8W4A6K2TJZ5H0N1PD"
  }
}

Status	Error type	When it happens
400	invalid_request	Malformed JSON or missing required fields
401	authentication_required	Missing or malformed Authorization header
403	forbidden	Key is valid but lacks the required scope
404	not_found	Resource doesn't exist or isn't yours
409	conflict	State conflict — e.g. IP already on allowlist
422	unprocessable_entity	Validation passed structure but failed business rules
429	rate_limited	You hit your per-key request limit. See Retry-After header.
500	internal_error	Something broke on our side. Retry with backoff.
503	service_unavailable	A downstream edge is offline. Retry with backoff.

Rate limits

Limits are per-key, counted against a sliding 60-second window. Every response carries the current budget in headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 284
X-RateLimit-Reset: 1714938000

Plan	Requests / minute	Burst
Starter	60	120 for 10s
Growth	300	600 for 10s
Scale	1200	2400 for 10s
Network	Custom	Custom

Versioning

Breaking changes ship behind a new version path (e.g./v2). Within a major version we only add fields — never remove them and never narrow their type. The current version pins to v1; pass an explicit X-API-Version header to lock the payload shape across deploys:

X-API-Version: 2026-04-01

Account

Account-level information for the key's owner.

GET/v1/me

Retrieve the authenticated account

Returns the account tied to the API key, plus the currently active plan.

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/me

Response

{
  "object": "account",
  "id": "acct_01HVQ8...",
  "email": "ops@example.com",
  "created_at": "2025-04-12T10:14:22Z",
  "plan": {
    "id": "growth",
    "name": "Growth",
    "status": "active",
    "current_period_end": "2026-05-12T10:14:22Z"
  }
}

GET/v1/usage

Bandwidth usage

Usage for the current billing cycle, broken down by exit class. Totals are in bytes.

Parameter	Type	Description
period	string	`current` (default), `previous`, or `YYYY-MM`
group_by	string	`class` (default) or `country`

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/usage

Response

{
  "object": "usage",
  "period_start": "2026-04-01T00:00:00Z",
  "period_end":   "2026-04-30T23:59:59Z",
  "total_bytes":  84122983241,
  "cap_bytes":   107374182400,
  "breakdown": [
    { "exit_class": "residential", "bytes": 52110000000 },
    { "exit_class": "isp",         "bytes": 22400000000 },
    { "exit_class": "mobile_4g",   "bytes":  7212983241 },
    { "exit_class": "mobile_5g",   "bytes":  2400000000 }
  ]
}

GET/v1/orders

List orders

Paginated list of orders on the account, newest first.

Parameter	Type	Description
status	string	`paid`, `pending`, `cancelled`, `expired`
limit	integer	Max 100. Defaults to 25.
cursor	string	Cursor returned in the previous response's `next_cursor`

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/orders

Response

{
  "object": "list",
  "data": [
    {
      "object": "order",
      "id": "ord_01HVQ8MKS2A...",
      "plan_id": "growth",
      "amount_usd": 99.00,
      "status": "paid",
      "payment_method": "card_c2c",
      "created_at": "2026-04-01T09:11:44Z",
      "paid_at":    "2026-04-01T09:12:08Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/v1/plans

List available plans

Public catalog — does not require an API key.

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/plans

Response

{
  "object": "list",
  "data": [
    { "id": "starter", "name": "Starter", "price_usd": 29,  "bandwidth_gb": 5 },
    { "id": "growth",  "name": "Growth",  "price_usd": 99,  "bandwidth_gb": 25 },
    { "id": "scale",   "name": "Scale",   "price_usd": 299, "bandwidth_gb": 100 },
    { "id": "network", "name": "Network", "price_usd": null, "bandwidth_gb": null }
  ]
}

Gateway

Manage the credentials your scrapers / clients use to connect to the proxy gateway.

GET/v1/credentials

Fetch active gateway credentials

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/credentials

Response

{
  "object": "credentials",
  "id": "cred_01HVQ...",
  "gateway": "gateway.proxaro.io",
  "port": 7777,
  "username": "nb_growth_a1b2c3d4",
  "password": "tN3Jx9-PeQ4sVWuM",
  "bandwidth_gb_cap":   25,
  "bandwidth_gb_used":  4.7,
  "expires_at": "2026-05-12T10:14:22Z"
}

POST/v1/credentials/rotate

Rotate the gateway password

Generates a fresh password and invalidates the old one within 60 seconds. In-flight connections are not dropped.

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/credentials/rotate

Response

{
  "object": "credentials",
  "id": "cred_01HVQ...",
  "rotated_at": "2026-04-22T14:30:00Z",
  "password": "f8Kq2-ZrV6W-xpY3"
}

GET/v1/sessions

List recent gateway sessions

Last 5,000 sessions in a rolling 24h window. Use for observability — not for billing (authoritative bandwidth lives on /v1/usage).

Parameter	Type	Description
limit	integer	Max 1000. Defaults to 100.
cursor	string	Pagination cursor
exit_class	string	Filter by `residential` \| `isp` \| `mobile_4g` \| `mobile_5g` \| `datacenter`

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/sessions

Response

{
  "object": "list",
  "data": [
    {
      "id": "sess_01HVQ...",
      "started_at": "2026-04-22T14:29:52Z",
      "ended_at":   "2026-04-22T14:30:11Z",
      "exit_ip":    "72.164.18.44",
      "exit_class": "residential",
      "exit_country": "us",
      "exit_asn":   "AS7922",
      "bytes_sent": 4218,
      "bytes_recv": 512341
    }
  ],
  "has_more": true,
  "next_cursor": "c_0uKf..."
}

Network

Discover what countries, cities, and ASNs are currently live in the pool so your scheduler doesn't target dead regions.

GET/v1/countries

List countries with live coverage

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/countries

Response

{
  "object": "list",
  "data": [
    {
      "code": "us",
      "name": "United States",
      "continent": "North America",
      "exit_classes": ["residential", "isp", "mobile_4g", "mobile_5g"],
      "cities_available": 47,
      "estimated_pool_size": 8200000
    }
  ]
}

GET/v1/countries/{code}/asns

List ASNs sizeable in a country

ASN-level targeting is available on Growth and above; starter keys will receive a 403 with `scope_required`.

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/countries/{code}/asns

Response

{
  "object": "list",
  "data": [
    { "asn": "AS7922", "org": "Comcast",    "exit_class": "residential", "pool_health": "healthy" },
    { "asn": "AS21928", "org": "T-Mobile", "exit_class": "mobile_4g",   "pool_health": "healthy" },
    { "asn": "AS22394", "org": "Verizon",  "exit_class": "mobile_5g",   "pool_health": "degraded" }
  ]
}

Allowlist

Pin the source IPs that are allowed to authenticate against your gateway. Empty allowlist = credentials-only auth.

GET/v1/allowlist

List allowlisted source IPs

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/allowlist

Response

{
  "object": "list",
  "data": [
    { "id": "al_01HVQ...", "cidr": "198.51.100.42/32", "label": "primary crawler", "created_at": "2026-04-01T10:00:00Z" },
    { "id": "al_01HVR...", "cidr": "203.0.113.0/24",   "label": "datacenter /24",  "created_at": "2026-04-03T18:12:00Z" }
  ]
}

POST/v1/allowlist

Add a source IP or CIDR

Parameter	Type	Description
cidrrequired	string	A single IPv4 / IPv6 address or a CIDR. Max prefix: /24 for IPv4, /48 for IPv6.
label	string	Human-readable note. Max 80 chars.

Request

curl -X POST https://api.proxaro.io/v1/allowlist \
  -H "Authorization: Bearer $PROXARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cidr": "198.51.100.42/32", "label": "primary crawler"}'

Response

{
  "object": "allowlist_entry",
  "id": "al_01HVQ...",
  "cidr": "198.51.100.42/32",
  "label": "primary crawler",
  "created_at": "2026-04-22T14:30:00Z"
}

DELETE/v1/allowlist/{id}

Remove an allowlist entry

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/allowlist/{id}

Response

{ "object": "allowlist_entry", "id": "al_01HVQ...", "deleted": true }

Webhooks

Subscribe a URL to receive events when important things happen on your account. Delivery is at-least-once with exponential backoff up to 24 hours; every request carries an X-NB-Signature header you verify with the endpoint's secret.

Event	When it fires
order.paid	An order transitions to paid
order.expired	A pending order hits its 24h TTL
credentials.rotated	Gateway password rotated (by API or UI)
usage.threshold.80	80% of the plan's bandwidth consumed
usage.threshold.100	Plan cap reached — overages begin
allowlist.updated	Entry added or removed

Signature verification

// Node
import crypto from "node:crypto";

function verify(body, header, secret) {
  const expected = crypto.createHmac("sha256", secret)
    .update(body).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(header),
  );
}

POST/v1/webhooks

Register a webhook endpoint

Parameter	Type	Description
urlrequired	string	HTTPS URL — HTTP is rejected.
eventsrequired	string[]	Event names. Use `["*"]` for everything.
label	string	Human-readable identifier.

Request

curl -X POST https://api.proxaro.io/v1/webhooks \
  -H "Authorization: Bearer $PROXARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://ops.example.com/hooks/nb",
    "events": ["order.paid", "usage.threshold.80"]
  }'

Response

{
  "object": "webhook",
  "id": "wh_01HVQ...",
  "url": "https://ops.example.com/hooks/nb",
  "events": ["order.paid", "usage.threshold.80"],
  "secret": "whsec_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "created_at": "2026-04-22T14:30:00Z"
}

GET/v1/webhooks

List registered webhooks

Secrets are only shown on creation. If you've lost one, rotate it with POST /v1/webhooks/{id}/rotate.

Example

curl -H "Authorization: Bearer $PROXARO_API_KEY" \
  https://api.proxaro.io/v1/webhooks

Official libraries

First-party SDKs wrap the REST API with idiomatic types and built-in retries. If your language isn't here, the REST API is straightforward to wrap in a few dozen lines.

Node.js

npm install @proxaro/sdk

import { Proxaro } from "@proxaro/sdk";

const client = new Proxaro(process.env.PROXARO_API_KEY);
const usage = await client.usage.get();
console.log(usage.total_bytes);

Python

pip install proxaro

from proxaro import Proxaro

client = Proxaro(api_key=os.environ["PROXARO_API_KEY"])
usage = client.usage.get()
print(usage.total_bytes)

Go

go get github.com/proxaro/proxaro-go

import "github.com/proxaro/proxaro-go"

client := proxaro.New(os.Getenv("PROXARO_API_KEY"))
u, _ := client.Usage.Get(ctx, nil)
fmt.Println(u.TotalBytes)

Changelog

2026-04-01
v1 goes stable
Pinned payload shapes, versioning header, published SDKs.
2026-02-14
Sessions endpoint
GET /v1/sessions returns per-session observability data.
2025-12-03
Webhook retry policy
Backoff now runs up to 24h; delivery receipts surfaced on GET /v1/webhooks/{id}/attempts.
2025-10-22
IPv6 allowlist
POST /v1/allowlist accepts IPv6 CIDRs up to /48.
2025-08-04
Initial release
Account, credentials, plans, orders endpoints shipped.

Something missing?

Email developers@proxaro.io or drop a question in our status page issue tracker. Endpoint requests that aren't blocked by compliance typically ship within two weeks.

GEThttps://api.proxaro.io/v1/statusreturns 200 OK when the API is healthy.

Quick start

Authentication

Errors

Rate limits

Versioning

Account

Retrieve the authenticated account

Bandwidth usage

List orders

List available plans

Gateway

Fetch active gateway credentials

Rotate the gateway password

List recent gateway sessions

Network

List countries with live coverage

List ASNs sizeable in a country

Allowlist

List allowlisted source IPs

Add a source IP or CIDR

Remove an allowlist entry

Webhooks

Signature verification

Register a webhook endpoint

List registered webhooks

Official libraries

Node.js

Python

Go

Changelog

v1 goes stable

Sessions endpoint

Webhook retry policy

IPv6 allowlist

Initial release

Something missing?