API v1

Proxly API. Proxies from your code.

Base URL
https://proxly.org/api/v1

Overview.

The API gives you what the dashboard does: the balance, your proxies with login and password, ready proxy strings with country, city and ASN targeting, traffic usage, orders and buying Residential and Datacenter GB from the balance.

  • Requests and answers are JSON in UTF-8.
  • Times are ISO 8601 in UTC, traffic is in GB.
  • Money is in roubles; dollars at the site's rate of 90 ₽ = $1.

Quick start.

  1. Confirm your e-mail and open Dashboard → API.
  2. Press «Create key», choose the rights — «Read only» or «Read and purchase» — and save the key: it is shown only once.
  3. Check the key with /account, then get the proxy strings of your access.
curl "https://proxly.org/api/v1/account" \
  -H "Authorization: Bearer pxl_your_key"

curl "https://proxly.org/api/v1/proxies" \
  -H "Authorization: Bearer pxl_your_key"

Authentication.

Every request carries the key in the Authorization: Bearer pxl_… header. The API does not accept the dashboard's sign-in cookies.

  • «Read only» — every GET request. «Read and purchase» — also buying traffic and changing an access password.
  • Up to 5 active keys per account. A revoked key stops working at once.
  • Changing or resetting the password and changing the e-mail revoke all the account's keys — create new ones afterwards. «Sign out other devices» leaves keys alone: revoke a suspicious key in the «API» section.
  • Every new key shows up in the dashboard notifications. If you did not create it, revoke it.
  • Never put the key into web page code, URLs or public repositories — it gives access to proxy passwords and the balance.

Responses and errors.

A successful answer is { "ok": true, "data": … }, an error is { "ok": false, "error": { "code", "message" } } with an HTTP status. Check code: message is an explanation in English.

401
{
  "ok": false,
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key. Send it as `Authorization: Bearer <key>`."
  }
}
HTTPcodeWhat happened
400bad_requestA wrong parameter or body — message says which one.
400idempotency_key_requiredA purchase needs the Idempotency-Key header.
400bad_paramsThis size cannot be bought: see min_gb, max_gb and packages in GET /products.
401unauthorizedNo key, a wrong key or a revoked one.
402insufficient_fundsNot enough money on the balance. Top it up in the dashboard.
403read_only_keyA read-only key cannot buy or change passwords.
403email_not_verifiedConfirm the account e-mail in the dashboard.
403account_unavailableThe account is not available — write to @proxly_sup.
404not_foundNo such method, proxy or order in your account.
405—The path exists, but not with this HTTP method (for example POST /account) — an empty answer.
409order_rejectedThe order was not placed for another reason — retry or write to @proxly_sup.
409unavailableThis size cannot be bought right now — try less or later.
409idempotency_conflictThis Idempotency-Key was already used for a different order.
409promo_unavailableThe promo code does not apply to the order.
409not_supportedThe action is not available for this proxy — for example, the order has no password of its own.
409expiredThe static proxy has expired — renew it in the dashboard.
409not_readyThe addresses are still being issued — retry in a few minutes.
429rate_limitedToo many requests. Retry after Retry-After seconds.
500server_errorAn error on our side. Try again later.
502temporarily_unavailableThe password was not changed; the old one works. Try again in a few minutes.
503sales_unavailablePurchases are temporarily unavailable.
503catalog_unavailablePrices did not load — retry in a minute.
503locations_unavailableCities and ASNs are not available — retry in a minute.
503password_change_unavailableChanging ISP and IPv4 passwords is temporarily unavailable.

Limits.

  • 120 requests a minute per key.
  • 20 purchases per 5 minutes per account, together with purchases in the dashboard.
  • Changing a rotating access password — up to 5 times an hour.
  • 60 wrong keys a minute from one address — then for a minute that address gets 429 for any key, a valid one too.
  • Over a limit — 429 rate_limited with a Retry-After header in seconds.

Account.

Account and balance

GET/api/v1/account

E-mail, whether it is confirmed, the balance in roubles and in dollars at the site's rate of 90 ₽ = $1, and the key's rights. Handy to check a key.

Any key

Response fields

idstring
Account id.
email, email_verifiedstring, boolean
The account e-mail and whether it is confirmed. Purchases need a confirmed e-mail.
balance_rub, balance_usdnumber
Balance. It is kept in roubles; dollars at the rate of 90.
key_scopestring
read — read only, write — read and purchase.
curl "https://proxly.org/api/v1/account" \
  -H "Authorization: Bearer pxl_your_key"
Response
{
  "ok": true,
  "data": {
    "id": "8b8c2639-23d7-49b9-bc23-b368fcd04445",
    "email": "you@example.com",
    "email_verified": true,
    "balance_rub": 2000,
    "balance_usd": 22.22,
    "key_scope": "write"
  }
}

Catalog.

Products and prices

GET/api/v1/products

What the API sells and at what price — the same prices as the site's price table, with volume discounts. The API buys Residential and Datacenter; ISP and IPv4 are ordered in the dashboard.

Any key

Response fields

typestring
residential or datacenter.
availableboolean
Whether it is on sale now.
min_gb, max_gbnumber
How many GB one order can buy.
packagesnumber[] | null
null — any whole number of GB from min_gb to max_gb; otherwise only these sizes.
pricesobject[]
Prices of popular sizes: gb, price_rub, price_usd and the price per GB. POST /orders returns the order's total.

The example is shortened: prices lists 1, 5, 10, 25, 50, 100, 500 and 1000 GB.

Request
curl "https://proxly.org/api/v1/products" \
  -H "Authorization: Bearer pxl_your_key"
Response
{
  "ok": true,
  "data": [
    {
      "type": "residential",
      "available": true,
      "unit": "gb",
      "min_gb": 1,
      "max_gb": 2000,
      "packages": null,
      "protocols": [
        "http",
        "socks5"
      ],
      "prices": [
        {
          "gb": 1,
          "price_rub": 108,
          "price_usd": 1.2,
          "per_gb_rub": 108,
          "per_gb_usd": 1.2
        },
        {
          "gb": 10,
          "price_rub": 900,
          "price_usd": 10,
          "per_gb_rub": 90,
          "per_gb_usd": 1
        },
        {
          "gb": 100,
          "price_rub": 7200,
          "price_usd": 80,
          "per_gb_rub": 72,
          "per_gb_usd": 0.8
        }
      ]
    },
    {
      "type": "datacenter",
      "available": true,
      "unit": "gb",
      "min_gb": 1,
      "max_gb": 2000,
      "packages": null,
      "protocols": [
        "http",
        "socks5"
      ],
      "prices": [
        {
          "gb": 1,
          "price_rub": 90,
          "price_usd": 1,
          "per_gb_rub": 90,
          "per_gb_usd": 1
        },
        {
          "gb": 10,
          "price_rub": 720,
          "price_usd": 8,
          "per_gb_rub": 72,
          "per_gb_usd": 0.8
        },
        {
          "gb": 100,
          "price_rub": 5400,
          "price_usd": 60,
          "per_gb_rub": 54,
          "per_gb_usd": 0.6
        }
      ]
    }
  ]
}

Countries, cities and ASNs

GET/api/v1/locations

The countries of a proxy type. With country — that country's cities, states and ASNs: their codes go into the proxy string.

Any key

Query parameters

typestring
residential (default) or datacenter.
countrystring
Two-letter country code, for example US.

This is the answer with country. Without country, data is the list of countries: [{ "code": "US", "name": "United States" }, …].

curl "https://proxly.org/api/v1/locations?type=datacenter&country=US" \
  -H "Authorization: Bearer pxl_your_key"
Response
{
  "ok": true,
  "data": {
    "code": "US",
    "name": "United States",
    "cities": [
      {
        "code": "new_york",
        "name": "New York"
      }
    ],
    "states": [
      {
        "code": "california",
        "name": "California"
      }
    ],
    "asns": [
      {
        "code": "7922",
        "name": "Comcast"
      }
    ]
  }
}

Proxies.

All proxies

GET/api/v1/proxies

Every access of the account, as in the dashboard: rotating ones (one access per type, bought GB add up), gifts and static ISP and IPv4. With login, password, ports and traffic left.

Any key

Response fields

idstring
Access id. A new account's gift is gift:residential or gift:datacenter.
typestring
residential, datacenter, isp or ipv4.
trialboolean
true for a gift access.
statusstring
Access state: active means it works.
host, portsstring, object
Address and ports: http, socks5 (one port for both on rotating proxies) and https. null means the protocol is not available.
username, passwordstring
The access login and password. Keep them like a password.
trafficobject | null
limit_gb, used_gb, remaining_gb for rotating proxies; null for static ones, their traffic is unmetered.
countrystring | null
Country of a static address. Rotating proxies take the country in the proxy string.
order_id, expires_at, created_atstring | null
The order, expiry and creation time (ISO 8601, UTC).
curl "https://proxly.org/api/v1/proxies" \
  -H "Authorization: Bearer pxl_your_key"
Response
{
  "ok": true,
  "data": [
    {
      "id": "3f1c9a52-7b0e-4d2a-9c61-2f8e4b7d0a13",
      "type": "residential",
      "trial": false,
      "status": "active",
      "host": "78.153.130.98",
      "ports": {
        "http": 8080,
        "socks5": 8080,
        "https": 8443
      },
      "username": "r6bad7d204c",
      "password": "Xk29fLq7",
      "traffic": {
        "limit_gb": 10,
        "used_gb": 2.418,
        "remaining_gb": 7.582
      },
      "country": null,
      "order_id": "c2a9e0d4-51f3-4b8e-a7d6-0e3b9f12c845",
      "expires_at": null,
      "created_at": "2026-10-20T09:14:03.000Z"
    }
  ]
}

One proxy

GET/api/v1/proxies/{id}

The same object as in the list, by access id.

Any key

Path parameters

idstringrequired
Access id from GET /proxies, or gift:residential / gift:datacenter.
Request
curl "https://proxly.org/api/v1/proxies/3f1c9a52-7b0e-4d2a-9c61-2f8e4b7d0a13" \
  -H "Authorization: Bearer pxl_your_key"
Response
{
  "ok": true,
  "data": {
    "id": "3f1c9a52-7b0e-4d2a-9c61-2f8e4b7d0a13",
    "type": "residential",
    "trial": false,
    "status": "active",
    "host": "78.153.130.98",
    "ports": {
      "http": 8080,
      "socks5": 8080,
      "https": 8443
    },
    "username": "r6bad7d204c",
    "password": "Xk29fLq7",
    "traffic": {
      "limit_gb": 10,
      "used_gb": 2.418,
      "remaining_gb": 7.582
    },
    "country": null,
    "order_id": "c2a9e0d4-51f3-4b8e-a7d6-0e3b9f12c845",
    "expires_at": null,
    "created_at": "2026-10-20T09:14:03.000Z"
  }
}

Proxy strings

GET/api/v1/proxies/{id}/endpoints

Ready proxy strings for apps and scripts, like the dashboard's generator: country, city, ASN, sticky sessions with an IP hold time. Country and session options are for rotating proxies; a static one returns its address. An option the proxy cannot use gives a 400 error, not a string without it.

Any key

Path parameters

idstringrequired
Access id.

Query parameters

protocolstring
http (default), https or socks5.
formatstring
host:port:user:pass (default), user:pass@host:port or url.
countrystring
Country code from GET /locations. Without it — any country.
citystring
City code from GET /locations (needs country).
statestring
State or region code, Datacenter only (needs country). Not together with city: the city already sets the region.
asnstring
Provider ASN from GET /locations (needs country).
osstring
windows, android, ios or mac — Datacenter only.
strictboolean
Datacenter only: true (default) — only an exact city, state or ASN match; false — a close address when there is no exact one.
sessionstring
rotating (default) — a new IP for every connection; sticky — the IP holds within a session.
countnumber
How many sticky sessions to return, 1–1000; only with session=sticky.
lifetimenumber
Minutes to hold the IP; only with session=sticky. Residential 1–30, Datacenter 5–1440.
curl "https://proxly.org/api/v1/proxies/3f1c9a52-7b0e-4d2a-9c61-2f8e4b7d0a13/endpoints?country=US&session=sticky&count=3&lifetime=30" \
  -H "Authorization: Bearer pxl_your_key"
Response
{
  "ok": true,
  "data": {
    "proxy_id": "3f1c9a52-7b0e-4d2a-9c61-2f8e4b7d0a13",
    "protocol": "http",
    "format": "host:port:user:pass",
    "session": "sticky",
    "endpoints": [
      "78.153.130.98:8080:r6bad7d204c-country-us-session-1-time-30:Xk29fLq7",
      "78.153.130.98:8080:r6bad7d204c-country-us-session-2-time-30:Xk29fLq7",
      "78.153.130.98:8080:r6bad7d204c-country-us-session-3-time-30:Xk29fLq7"
    ]
  }
}

Traffic usage

GET/api/v1/proxies/{id}/usage

Usage of a rotating access by hour (24h) or by day (7d, 30d), in GB. Static proxies are not metered: metered = false.

Any key

Path parameters

idstringrequired
Access id.

Query parameters

periodstring
24h (default), 7d or 30d.

The example shows two of the seven days.

Request
curl "https://proxly.org/api/v1/proxies/3f1c9a52-7b0e-4d2a-9c61-2f8e4b7d0a13/usage?period=7d" \
  -H "Authorization: Bearer pxl_your_key"
Response
{
  "ok": true,
  "data": {
    "proxy_id": "3f1c9a52-7b0e-4d2a-9c61-2f8e4b7d0a13",
    "period": "7d",
    "step": "day",
    "metered": true,
    "total_gb": 2.418,
    "series": [
      {
        "at": "2026-10-21T00:00:00.000Z",
        "gb": 0.312
      },
      {
        "at": "2026-10-22T00:00:00.000Z",
        "gb": 0.588
      }
    ]
  }
}

New password

POST/api/v1/proxies/{id}/password

Gives a new random password; the old one stops working at once. The login stays. ISP and IPv4 have one login for the whole order, so the password changes for every address of that order. The answer is the access with the new password.

«Read and purchase» key

Path parameters

idstringrequired
Access id.

Up to 5 times an hour per access (for ISP and IPv4 — per order, and up to 20 an hour per account). ISP and IPv4 need a confirmed e-mail.

Request
curl "https://proxly.org/api/v1/proxies/3f1c9a52-7b0e-4d2a-9c61-2f8e4b7d0a13/password" \
  -H "Authorization: Bearer pxl_your_key" \
  -X POST
Response
{
  "ok": true,
  "data": {
    "id": "3f1c9a52-7b0e-4d2a-9c61-2f8e4b7d0a13",
    "type": "residential",
    "trial": false,
    "status": "active",
    "host": "78.153.130.98",
    "ports": {
      "http": 8080,
      "socks5": 8080,
      "https": 8443
    },
    "username": "r6bad7d204c",
    "password": "Tq84mZr2",
    "traffic": {
      "limit_gb": 10,
      "used_gb": 2.418,
      "remaining_gb": 7.582
    },
    "country": null,
    "order_id": "c2a9e0d4-51f3-4b8e-a7d6-0e3b9f12c845",
    "expires_at": null,
    "created_at": "2026-10-20T09:14:03.000Z"
  }
}

Orders.

Orders

GET/api/v1/orders

The account's orders, newest first, a page at a time. For the next page pass before = next_before from the answer.

Any key

Query parameters

limitnumber
Orders per page, 1–100, default 50.
beforestring
next_before of the previous page.

Response fields

itemsobject[]
The orders of the page.
has_more, next_beforeboolean, string | null
Whether there are more orders and what to pass as before.
id, type, statusstring
Id, proxy type and order state (paid, provisioning, active, expired, refunded and others).
gb, quantity, monthsnumber | null
GB of a rotating order, or addresses and months of a static one.
price_rubnumber
What was paid, in roubles.
access_order_idstring
The order of the access that got the GB: an earlier order for a top-up, otherwise this one. Find the access in GET /proxies by order_id.
Request
curl "https://proxly.org/api/v1/orders?limit=20" \
  -H "Authorization: Bearer pxl_your_key"
Response
{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "c2a9e0d4-51f3-4b8e-a7d6-0e3b9f12c845",
        "type": "residential",
        "status": "active",
        "gb": 10,
        "quantity": null,
        "months": null,
        "country": null,
        "price_rub": 900,
        "trial": false,
        "access_order_id": "c2a9e0d4-51f3-4b8e-a7d6-0e3b9f12c845",
        "created_at": "2026-10-20T09:13:58.000Z",
        "updated_at": "2026-10-20T09:14:03.000Z"
      }
    ],
    "has_more": false,
    "next_before": null
  }
}

One order

GET/api/v1/orders/{id}

An order by id — for example, to wait for delivery after a purchase.

Any key

Path parameters

idstringrequired
Order id.
Request
curl "https://proxly.org/api/v1/orders/c2a9e0d4-51f3-4b8e-a7d6-0e3b9f12c845" \
  -H "Authorization: Bearer pxl_your_key"
Response
{
  "ok": true,
  "data": {
    "id": "c2a9e0d4-51f3-4b8e-a7d6-0e3b9f12c845",
    "type": "residential",
    "status": "active",
    "gb": 10,
    "quantity": null,
    "months": null,
    "country": null,
    "price_rub": 900,
    "trial": false,
    "access_order_id": "c2a9e0d4-51f3-4b8e-a7d6-0e3b9f12c845",
    "created_at": "2026-10-20T09:13:58.000Z",
    "updated_at": "2026-10-20T09:14:03.000Z"
  }
}

Buy traffic

POST/api/v1/orders

Buys GB of Residential or Datacenter from the account balance. If a matching access of that type exists, the GB are added to it — the login and password stay; topped_up and access_order_id tell you whether that happened. Needs a «Read and purchase» key and a confirmed e-mail.

«Read and purchase» key

Headers

Idempotency-Keystringrequired
Your unique purchase id: 8–128 printable ASCII characters without spaces, for example a UUID. A retry with the same id does not charge twice and returns the same order.

Request body (JSON)

typestringrequired
residential or datacenter.
gbnumberrequired
A whole number of GB within min_gb–max_gb from GET /products.
currencystring
RUB (default) or USD — which price list to use. The balance is always charged in roubles.
promo_codestring
A promo code, if you have one.

Response fields

order_idstring
The new order's id.
price_rub, discount_rub, charged_rubnumber
Price before the discount, the discount and the amount charged to the balance.
balance_rubnumber
Balance after the purchase.
topped_up, access_order_idboolean, string
true — the GB were added to an existing access; access_order_id — that access's order_id in GET /proxies.
statusstring
The order state right after payment: paid, provisioning or active.
replayedboolean
true — a retry with the same Idempotency-Key (200 instead of 201).

Delivery takes seconds. While the order is paid or provisioning, poll it with GET /orders/{id}.

curl "https://proxly.org/api/v1/orders" \
  -X POST \
  -H "Authorization: Bearer pxl_your_key" \
  -H "Idempotency-Key: 7d1f0c2e-buy-10gb" \
  -H "Content-Type: application/json" \
  -d '{"type":"residential","gb":10}'
Response
{
  "ok": true,
  "data": {
    "order_id": "e41b7c09-2d5a-4f6e-8b13-9a0c7e2f5d61",
    "type": "residential",
    "gb": 10,
    "price_rub": 900,
    "discount_rub": 0,
    "charged_rub": 900,
    "balance_rub": 1100,
    "topped_up": true,
    "access_order_id": "c2a9e0d4-51f3-4b8e-a7d6-0e3b9f12c845",
    "status": "paid",
    "replayed": false
  }
}

White-label Soon

Resell Proxly proxies under your own brand: your customers, your prices and sub-accounts with their own traffic limits. Want early access — write to @proxly_sup.