Proxy API

The AeonProxy API is a JSON REST API at https://aeonproxy.com/api/v1. It works with the same account, traffic and logins as the dashboard: a proxy list you generate here works on the gateway at once, a sub-user you create shows up in the dashboard, and traffic you buy is in the same balance.

Every account has an API key, at no extra cost. API calls use no traffic: only the requests you send through the proxies count.

Quickstart

1. Sign in and copy the key from Settings → API. It starts with ap_live_.
2. Keep it out of your code: put it in an environment variable.
3. Call Get the account. A balance in the answer means the key works.

export AEONPROXY_API_KEY="ap_live_…"
curl "https://aeonproxy.com/api/v1/me" -H "Authorization: Bearer $AEONPROXY_API_KEY"

Then generate a proxy list for your tool, or create a sub-user for each project.

Authentication

Send the key in the Authorization header of every request: Authorization: Bearer ap_live_…. Clients that cannot set it can send X-API-Key: ap_live_… instead. Keys never go in the URL.

A request without a valid key gets 401. The key belongs to the account, not to a person: it can do everything below, including buying traffic with the balance, but it cannot open the dashboard, rotate itself or request payouts. Rotating it in Settings → API asks for your password, and the old key stops working at once.

The key is for the API only. Proxy traffic uses your proxy login and password on gate.aeonproxy.com, as described in the gateway documentation.

Requests and answers

Base URL: https://aeonproxy.com/api/v1. Requests with a body send JSON (Content-Type: application/json); answers are JSON, apart from proxy lists you ask for as text. Names are in snake_case.

• Products are residential and mobile (orders also show isp and datacenter).
• Traffic is in GB, where 1 GB is 10⁹ bytes, as on your invoices. Money is in US dollars, as a number (balance_usd: 42.5).
• Times are ISO 8601 in UTC (2026-10-28T09:30:00.000Z).
• Lists answer { "count", "results" }; long ones page with limit and offset.

Within v1 we only add things: new endpoints, new optional parameters and new fields in answers. Ignore fields your code does not know, and it will keep working.

Errors

A failed request answers with an HTTP status of 400 or above and the same body every time. code is stable and meant for your code; message is written for people and may change; param names the parameter at fault, when there is one.

{
  "error": {
    "code": "invalid_parameter",
    "message": "Unknown country for residential: \"xx\". GET /locations/countries lists them.",
    "param": "country"
  }
}

Errors of the proxy gateway itself (407, 402, 502 on a proxy connection) are listed in the gateway documentation.

Rate limits

Each key can make 120 requests per minute, and 10 of them can be purchases. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (a Unix time). Over the limit you get 429 with Retry-After in seconds.

The limit is on API calls only: proxy connections through the gateway have no thread limit. If you need a long list of cities or proxies, ask for a bigger page instead of many small ones.

Retries and the Idempotency-Key

Buy traffic and Create a sub-user accept an Idempotency-Key header: any unique string up to 64 characters, such as a UUID. If the connection drops before you get the answer, send the same request with the same key. You get the first answer back (with Idempotent-Replayed: true) instead of a second purchase. Keys are kept for 24 hours. A request that failed can be sent again with the same key.

All endpoints

OpenAPI and Postman

The whole API is described in one OpenAPI 3.1 file, built from the same source as these pages. Import it into Postman, Insomnia or Bruno, generate a client for your language with OpenAPI Generator, or give it to an AI agent as a tool definition. A ready Postman collection has every request with its example; set the apiKey variable to your key.