{ "openapi": "3.1.0", "info": { "title": "AeonProxy API", "version": "v1", "description": "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.\n\nEvery account has an API key, at no extra cost. API calls use no traffic: only the requests you send through the proxies count.\n\nRate limit: 120 requests per minute per key. Errors: `{ \"error\": { \"code\", \"message\", \"param\" } }`. Reference with examples: https://aeonproxy.com/docs/api", "contact": { "name": "AeonProxy support", "url": "https://aeonproxy.com/contact", "email": "support@aeonproxy.com" }, "termsOfService": "https://aeonproxy.com/terms" }, "externalDocs": { "description": "API reference", "url": "https://aeonproxy.com/docs/api" }, "servers": [ { "url": "https://aeonproxy.com/api/v1" } ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "tags": [ { "name": "Account", "description": "Balance, traffic left on each product, the main proxy login and its password.", "externalDocs": { "url": "https://aeonproxy.com/docs/api/account" } }, { "name": "Locations", "description": "Every country, region, city, ISP and carrier you can target, with the value to put in the proxy login.", "externalDocs": { "url": "https://aeonproxy.com/docs/api/locations" } }, { "name": "Proxy lists", "description": "Ready proxy lines for your scraper, antidetect browser or bot: up to 500 per call, in the format your tool reads.", "externalDocs": { "url": "https://aeonproxy.com/docs/api/proxy-list" } }, { "name": "Sub-users", "description": "Separate logins for team members, projects and applications, each with its own traffic limit.", "externalDocs": { "url": "https://aeonproxy.com/docs/api/sub-users" } }, { "name": "Usage", "description": "Traffic, requests and success rate by hour or by day, for the last 30 days.", "externalDocs": { "url": "https://aeonproxy.com/docs/api/usage" } }, { "name": "Orders", "description": "Price quotes with your discounts, traffic purchases from the balance, and your order history.", "externalDocs": { "url": "https://aeonproxy.com/docs/api/orders" } } ], "paths": { "/status": { "get": { "operationId": "getStatus", "summary": "Check the API", "tags": [ "Account" ], "description": "Answers without a key. Use it in health checks and to see the API version.\n\nReference: https://aeonproxy.com/docs/api/account#get-status", "parameters": [], "responses": { "200": { "description": "Check the API", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "api_version": { "type": "string" }, "time": { "type": "string" } } }, "example": { "status": "ok", "api_version": "v1", "time": "2026-10-28T09:30:00.000Z" } } } } }, "security": [] } }, "/me": { "get": { "operationId": "getAccount", "summary": "Get the account", "tags": [ "Account" ], "description": "The balance, the traffic you have bought and used per product, the number of sub-users and active orders. Traffic counts in GB (1 GB = 10⁹ bytes), money in US dollars.\n\nReference: https://aeonproxy.com/docs/api/account#get-account", "parameters": [], "responses": { "200": { "description": "Get the account", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email": { "type": "string" }, "created_at": { "type": "string" }, "balance_usd": { "type": "number" }, "traffic": { "type": "object", "properties": { "residential": { "type": "object", "properties": { "gb_total": { "type": "integer" }, "gb_used": { "type": "number" }, "gb_left": { "type": "number" } } }, "mobile": { "type": "object", "properties": { "gb_total": { "type": "integer" }, "gb_used": { "type": "integer" }, "gb_left": { "type": "integer" } } } } }, "sub_users": { "type": "object", "properties": { "residential": { "type": "integer" }, "mobile": { "type": "integer" } } }, "active_orders": { "type": "integer" } } }, "example": { "id": 1042, "email": "you@example.com", "created_at": "2026-10-20T09:14:03.000Z", "balance_usd": 42.5, "traffic": { "residential": { "gb_total": 25, "gb_used": 6.204, "gb_left": 18.796 }, "mobile": { "gb_total": 0, "gb_used": 0, "gb_left": 0 } }, "sub_users": { "residential": 3, "mobile": 0 }, "active_orders": 2 } } } }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/credentials": { "get": { "operationId": "getCredentials", "summary": "Get proxy credentials", "tags": [ "Account" ], "description": "The main proxy login of one product, the gateway host and ports, and the traffic left. Append [targeting keys](https://aeonproxy.com/docs#targeting) to `username` (`-cc-us`, `-sid-…`), or let [Generate a proxy list](https://aeonproxy.com/docs/api/proxy-list#generate-proxy-list) build the lines.\n\nReference: https://aeonproxy.com/docs/api/account#get-credentials", "parameters": [ { "name": "product", "in": "query", "required": true, "description": "Which pool: `residential` or `mobile`.", "schema": { "type": "string", "enum": [ "residential", "mobile" ] } } ], "responses": { "200": { "description": "Get proxy credentials", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "host": { "type": "string" }, "port_http": { "type": "integer" }, "port_socks5": { "type": "integer" }, "username": { "type": "string" }, "password": { "type": "string" }, "traffic": { "type": "object", "properties": { "gb_total": { "type": "integer" }, "gb_used": { "type": "number" }, "gb_left": { "type": "number" } } } } }, "example": { "product": "residential", "host": "gate.aeonproxy.com", "port_http": 7000, "port_socks5": 7001, "username": "ap_u1a2b", "password": "Xr7pQ2mK9sLd", "traffic": { "gb_total": 25, "gb_used": 6.204, "gb_left": 18.796 } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/credentials/password": { "post": { "operationId": "rotatePassword", "summary": "Rotate the proxy password", "tags": [ "Account" ], "description": "Gives the main login of one product a new password. The old one stops working at once, in every proxy line that uses it; sub-users keep theirs.\n\nReference: https://aeonproxy.com/docs/api/account#rotate-password", "parameters": [], "responses": { "200": { "description": "Rotate the proxy password", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" } } }, "example": { "product": "residential", "username": "ap_u1a2b", "password": "Ws8nB3xR6pYc" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "type": "string", "enum": [ "residential", "mobile" ], "description": "Which pool: `residential` or `mobile`." } } }, "example": { "product": "residential" } } } } } }, "/locations/countries": { "get": { "operationId": "listCountries", "summary": "List countries", "tags": [ "Locations" ], "description": "Countries with exits on the product right now. `code` is what `country` and the `-cc-` key take.\n\nReference: https://aeonproxy.com/docs/api/locations#list-countries", "parameters": [ { "name": "product", "in": "query", "required": true, "description": "Which pool: `residential` or `mobile`.", "schema": { "type": "string", "enum": [ "residential", "mobile" ] } } ], "responses": { "200": { "description": "List countries", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } } } } } }, "example": { "product": "residential", "count": 3, "results": [ { "code": "us", "name": "United States" }, { "code": "gb", "name": "United Kingdom" }, { "code": "de", "name": "Germany" } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/locations/regions": { "get": { "operationId": "listRegions", "summary": "List regions", "tags": [ "Locations" ], "description": "States, provinces or nations of one country. The slug goes into the `-st-` key: `ap_…-cc-us-st-newyork`.\n\nReference: https://aeonproxy.com/docs/api/locations#list-regions", "parameters": [ { "name": "product", "in": "query", "required": true, "description": "Which pool: `residential` or `mobile`.", "schema": { "type": "string", "enum": [ "residential", "mobile" ] } }, { "name": "country", "in": "query", "required": true, "description": "Two-letter country code from [countries](https://aeonproxy.com/docs/api/locations#list-countries), e.g. `us`, `gb`, `de`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List regions", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "country": { "type": "string" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "example": { "product": "residential", "country": "us", "count": 3, "results": [ { "name": "california", "slug": "california" }, { "name": "new york", "slug": "newyork" }, { "name": "texas", "slug": "texas" } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/locations/cities": { "get": { "operationId": "listCities", "summary": "List cities", "tags": [ "Locations" ], "description": "Cities of one country, filtered by `search` and paged with `limit` and `offset` (the United States alone has thousands). `count` is the number of matches before paging. The slug goes into the `-city-` key.\n\nReference: https://aeonproxy.com/docs/api/locations#list-cities", "parameters": [ { "name": "product", "in": "query", "required": true, "description": "Which pool: `residential` or `mobile`.", "schema": { "type": "string", "enum": [ "residential", "mobile" ] } }, { "name": "country", "in": "query", "required": true, "description": "Two-letter country code from [countries](https://aeonproxy.com/docs/api/locations#list-countries), e.g. `us`, `gb`, `de`.", "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "description": "Only cities whose name contains this text (case-insensitive).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 1000 } }, { "name": "offset", "in": "query", "required": false, "description": "How many matches to skip.", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "List cities", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "country": { "type": "string" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "example": { "product": "residential", "country": "us", "count": 41, "limit": 3, "offset": 0, "results": [ { "name": "san antonio", "slug": "sanantonio" }, { "name": "san diego", "slug": "sandiego" }, { "name": "san francisco", "slug": "sanfrancisco" } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/locations/isps": { "get": { "operationId": "listIsps", "summary": "List ISPs and carriers", "tags": [ "Locations" ], "description": "Home ISPs (residential) or mobile carriers (mobile) of one country. Residential logins take the slug in `-isp-`, mobile ones in `-car-`. An empty list means the country has no network targeting yet.\n\nReference: https://aeonproxy.com/docs/api/locations#list-isps", "parameters": [ { "name": "product", "in": "query", "required": true, "description": "Which pool: `residential` or `mobile`.", "schema": { "type": "string", "enum": [ "residential", "mobile" ] } }, { "name": "country", "in": "query", "required": true, "description": "Two-letter country code from [countries](https://aeonproxy.com/docs/api/locations#list-countries), e.g. `us`, `gb`, `de`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List ISPs and carriers", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "country": { "type": "string" }, "kind": { "type": "string" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "example": { "product": "residential", "country": "us", "kind": "isp", "count": 2, "results": [ { "name": "comcast cable", "slug": "comcastcable" }, { "name": "charter communications", "slug": "chartercommunications" } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/proxy-list": { "post": { "operationId": "generateProxyList", "summary": "Generate a proxy list", "tags": [ "Proxy lists" ], "description": "Returns `count` lines as JSON, each split into host, port, username and password and joined in your `format`. Send `\"output\": \"text\"` to get plain text, one line per row.\n\nReference: https://aeonproxy.com/docs/api/proxy-list#generate-proxy-list", "parameters": [], "responses": { "200": { "description": "Generate a proxy list", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "session": { "type": "string" }, "ttl": { "type": "integer" }, "protocol": { "type": "string" }, "format": { "type": "string" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "username": { "type": "string" }, "password": { "type": "string" }, "proxy": { "type": "string" } } } } } }, "example": { "product": "residential", "session": "sticky", "ttl": 30, "protocol": "http", "format": "host:port:user:pass", "count": 3, "results": [ { "host": "gate.aeonproxy.com", "port": 7000, "username": "ap_u1a2b-cc-us-st-newyork-sid-4f2a9c1e-ttl-30", "password": "Xr7pQ2mK9sLd", "proxy": "gate.aeonproxy.com:7000:ap_u1a2b-cc-us-st-newyork-sid-4f2a9c1e-ttl-30:Xr7pQ2mK9sLd" }, { "host": "gate.aeonproxy.com", "port": 7000, "username": "ap_u1a2b-cc-us-st-newyork-sid-b71d03aa-ttl-30", "password": "Xr7pQ2mK9sLd", "proxy": "gate.aeonproxy.com:7000:ap_u1a2b-cc-us-st-newyork-sid-b71d03aa-ttl-30:Xr7pQ2mK9sLd" }, { "host": "gate.aeonproxy.com", "port": 7000, "username": "ap_u1a2b-cc-us-st-newyork-sid-9e5c62f0-ttl-30", "password": "Xr7pQ2mK9sLd", "proxy": "gate.aeonproxy.com:7000:ap_u1a2b-cc-us-st-newyork-sid-9e5c62f0-ttl-30:Xr7pQ2mK9sLd" } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product" ], "properties": { "product": { "type": "string", "enum": [ "residential", "mobile" ], "description": "Which pool: `residential` or `mobile`." }, "country": { "type": "string", "description": "Country code from [List countries](https://aeonproxy.com/docs/api/locations#list-countries). Omit for any country." }, "region": { "type": "string", "description": "Region name or slug from [List regions](https://aeonproxy.com/docs/api/locations#list-regions). Needs `country`." }, "city": { "type": "string", "description": "City name or slug from [List cities](https://aeonproxy.com/docs/api/locations#list-cities). Needs `country`." }, "isp": { "type": "string", "description": "Residential only: ISP from [List ISPs](https://aeonproxy.com/docs/api/locations#list-isps). Needs `country`." }, "carrier": { "type": "string", "description": "Mobile only: carrier from [List ISPs](https://aeonproxy.com/docs/api/locations#list-isps). Needs `country`." }, "session": { "type": "string", "enum": [ "sticky", "rotating" ], "default": "sticky", "description": "`sticky`: one exit IP per line for `ttl` minutes. `rotating`: a new exit IP on every connection." }, "ttl": { "type": "integer", "default": 10, "minimum": 1, "maximum": 60, "description": "Sticky only: minutes each line keeps its IP." }, "protocol": { "type": "string", "enum": [ "http", "socks5" ], "default": "http", "description": "`http` (HTTP and HTTPS, port 7000) or `socks5` (port 7001, TCP and UDP)." }, "count": { "type": "integer", "default": 10, "minimum": 1, "maximum": 500, "description": "How many lines." }, "format": { "type": "string", "enum": [ "host:port:user:pass", "host:port@user:pass", "user:pass:host:port", "user:pass@host:port", "protocol://user:pass@host:port" ], "default": "host:port:user:pass", "description": "How `proxy` joins the parts. `protocol://…` writes `http://` or `socks5://`." }, "sub_user_id": { "type": "integer", "description": "Build the lines on a [sub-user's](https://aeonproxy.com/docs/api/sub-users) login (same product) instead of the main one, so its traffic limit applies." }, "output": { "type": "string", "enum": [ "json", "text" ], "default": "json", "description": "`text` answers `text/plain` with one `proxy` per line." } } }, "example": { "product": "residential", "country": "us", "region": "new york", "session": "sticky", "ttl": 30, "count": 3 } } } } }, "get": { "operationId": "downloadProxyList", "summary": "Download a proxy list", "tags": [ "Proxy lists" ], "description": "The same generator with the parameters in the query string, for tools that only fetch a URL and for `curl … > proxies.txt`. With `output=text` the answer is plain text. URL-encode `format`: `user%3Apass%40host%3Aport`.\n\nReference: https://aeonproxy.com/docs/api/proxy-list#download-proxy-list", "parameters": [ { "name": "product", "in": "query", "required": true, "description": "Which pool: `residential` or `mobile`.", "schema": { "type": "string", "enum": [ "residential", "mobile" ] } }, { "name": "country", "in": "query", "required": false, "description": "As in [Generate a proxy list](https://aeonproxy.com/docs/api/proxy-list#generate-proxy-list); so are `region`, `city`, `isp`, `carrier`, `ttl`, `protocol`, `format` and `sub_user_id`.", "schema": { "type": "string" } }, { "name": "session", "in": "query", "required": false, "description": "Sticky or rotating lines.", "schema": { "type": "string", "enum": [ "sticky", "rotating" ], "default": "sticky" } }, { "name": "count", "in": "query", "required": false, "description": "How many lines.", "schema": { "type": "integer", "default": 10, "minimum": 1, "maximum": 500 } }, { "name": "output", "in": "query", "required": false, "description": "`text` answers `text/plain`, one line per row.", "schema": { "type": "string", "enum": [ "json", "text" ], "default": "json" } } ], "responses": { "200": { "description": "Proxy lines, one per row", "content": { "text/plain": { "schema": { "type": "string" }, "example": "ap_u1a2b-cc-us-st-newyork-sid-4f2a9c1e-ttl-30:Xr7pQ2mK9sLd@gate.aeonproxy.com:7000\nap_u1a2b-cc-us-st-newyork-sid-b71d03aa-ttl-30:Xr7pQ2mK9sLd@gate.aeonproxy.com:7000\nap_u1a2b-cc-us-st-newyork-sid-9e5c62f0-ttl-30:Xr7pQ2mK9sLd@gate.aeonproxy.com:7000" } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/sub-users": { "get": { "operationId": "listSubUsers", "summary": "List sub-users", "tags": [ "Sub-users" ], "description": "All sub-users, or those of one product.\n\nReference: https://aeonproxy.com/docs/api/sub-users#list-sub-users", "parameters": [ { "name": "product", "in": "query", "required": false, "description": "`residential` or `mobile`. Omit for both.", "schema": { "type": "string", "enum": [ "residential", "mobile" ] } } ], "responses": { "200": { "description": "List sub-users", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "product": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "limit_gb": { "type": "integer" }, "used_gb": { "type": "number" }, "status": { "type": "string" }, "created_at": { "type": "string" } } } } } }, "example": { "count": 1, "results": [ { "id": 311, "product": "residential", "name": "scraper-eu", "username": "ap_7f3c", "password": "Lm4vT9qZ2wKe", "limit_gb": 5, "used_gb": 1.274, "status": "active", "created_at": "2026-10-21T08:12:44.000Z" } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } }, "post": { "operationId": "createSubUser", "summary": "Create a sub-user", "tags": [ "Sub-users" ], "description": "Creates a login with a random password. The name is stored in lower case, with anything other than letters, digits and dashes turned into dashes. Send an `Idempotency-Key` header to retry safely.\n\nReference: https://aeonproxy.com/docs/api/sub-users#create-sub-user", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 64 characters; a retry with the same key gets the first answer back.", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "201": { "description": "Create a sub-user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "product": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "limit_gb": { "type": "integer" }, "used_gb": { "type": "integer" }, "status": { "type": "string" }, "created_at": { "type": "string" } } }, "example": { "id": 311, "product": "residential", "name": "scraper-eu", "username": "ap_7f3c", "password": "Lm4vT9qZ2wKe", "limit_gb": 5, "used_gb": 0, "status": "active", "created_at": "2026-10-21T08:12:44.000Z" } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product", "name" ], "properties": { "product": { "type": "string", "enum": [ "residential", "mobile" ], "description": "Which pool: `residential` or `mobile`." }, "name": { "type": "string", "description": "Up to 24 characters, unique per product." }, "limit_gb": { "type": "number", "default": 0, "minimum": 0, "description": "Traffic limit in GB, in steps of 0.1. `0`: no limit of its own. Capped at the traffic you have bought." } } }, "example": { "product": "residential", "name": "scraper-eu", "limit_gb": 5 } } } } } }, "/sub-users/{id}": { "get": { "operationId": "getSubUser", "summary": "Get a sub-user", "tags": [ "Sub-users" ], "description": "One sub-user with its login, password, limit and the traffic it has used.\n\nReference: https://aeonproxy.com/docs/api/sub-users#get-sub-user", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The sub-user id from [List sub-users](https://aeonproxy.com/docs/api/sub-users#list-sub-users).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Get a sub-user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "product": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "limit_gb": { "type": "integer" }, "used_gb": { "type": "number" }, "status": { "type": "string" }, "created_at": { "type": "string" } } }, "example": { "id": 311, "product": "residential", "name": "scraper-eu", "username": "ap_7f3c", "password": "Lm4vT9qZ2wKe", "limit_gb": 5, "used_gb": 1.274, "status": "active", "created_at": "2026-10-21T08:12:44.000Z" } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } }, "patch": { "operationId": "updateSubUser", "summary": "Update a sub-user", "tags": [ "Sub-users" ], "description": "Renames a sub-user or changes its limit; send only the fields to change. The login and password stay the same. Lowering the limit below what it has used stops it at once.\n\nReference: https://aeonproxy.com/docs/api/sub-users#update-sub-user", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The sub-user id from [List sub-users](https://aeonproxy.com/docs/api/sub-users#list-sub-users).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Update a sub-user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "product": { "type": "string" }, "name": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" }, "limit_gb": { "type": "integer" }, "used_gb": { "type": "number" }, "status": { "type": "string" }, "created_at": { "type": "string" } } }, "example": { "id": 311, "product": "residential", "name": "scraper-eu", "username": "ap_7f3c", "password": "Lm4vT9qZ2wKe", "limit_gb": 10, "used_gb": 1.274, "status": "active", "created_at": "2026-10-21T08:12:44.000Z" } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "429": { "$ref": "#/components/responses/E429" } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name, same rules as on create." }, "limit_gb": { "type": "number", "minimum": 0, "description": "New limit in GB; `0` removes it." } } }, "example": { "limit_gb": 10 } } } } }, "delete": { "operationId": "deleteSubUser", "summary": "Delete a sub-user", "tags": [ "Sub-users" ], "description": "Deletes the login: its proxy lines stop working at once. The traffic it used stays used; nothing is refunded to the account.\n\nReference: https://aeonproxy.com/docs/api/sub-users#delete-sub-user", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The sub-user id from [List sub-users](https://aeonproxy.com/docs/api/sub-users#list-sub-users).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Delete a sub-user", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "deleted": { "type": "boolean" } } }, "example": { "id": 311, "deleted": true } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/sub-users/{id}/password": { "post": { "operationId": "rotateSubUserPassword", "summary": "Rotate a sub-user password", "tags": [ "Sub-users" ], "description": "Gives the sub-user a new password; the old one stops working at once.\n\nReference: https://aeonproxy.com/docs/api/sub-users#rotate-sub-user-password", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The sub-user id from [List sub-users](https://aeonproxy.com/docs/api/sub-users#list-sub-users).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Rotate a sub-user password", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "username": { "type": "string" }, "password": { "type": "string" } } }, "example": { "id": 311, "username": "ap_7f3c", "password": "Qd2hN7yV4cPa" } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/usage": { "get": { "operationId": "getUsage", "summary": "Get usage", "tags": [ "Usage" ], "description": "A series of points, one per hour (`24h`) or per day (`7d`, `30d`), with totals. Points without traffic are included with zeros, so the series has no gaps. `success_rate` is a percentage, or `null` without requests.\n\nReference: https://aeonproxy.com/docs/api/usage#get-usage", "parameters": [ { "name": "product", "in": "query", "required": true, "description": "Which pool: `residential` or `mobile`.", "schema": { "type": "string", "enum": [ "residential", "mobile" ] } }, { "name": "period", "in": "query", "required": false, "description": "`24h`: the last 24 hours, by hour. `7d` / `30d`: the last 7 or 30 days, by day, today included.", "schema": { "type": "string", "enum": [ "24h", "7d", "30d" ], "default": "7d" } }, { "name": "sub_user_id", "in": "query", "required": false, "description": "Only this sub-user.", "schema": { "type": "integer" } }, { "name": "include_sub_users", "in": "query", "required": false, "description": "Without `sub_user_id`: `true` counts the whole account, `false` only the main login.", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Get usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "period": { "type": "string" }, "granularity": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "totals": { "type": "object", "properties": { "gb": { "type": "number" }, "requests": { "type": "integer" }, "success_rate": { "type": "number" } } }, "series": { "type": "array", "items": { "type": "object", "properties": { "start": { "type": "string" }, "gb": { "type": "integer" }, "requests": { "type": "integer" }, "success_rate": {} } } } } }, "example": { "product": "residential", "period": "7d", "granularity": "day", "from": "2026-10-22T00:00:00.000Z", "to": "2026-10-28T09:30:00.000Z", "totals": { "gb": 6.204, "requests": 18342, "success_rate": 98.7 }, "series": [ { "start": "2026-10-22T00:00:00.000Z", "gb": 0, "requests": 0, "success_rate": null }, { "start": "2026-10-23T00:00:00.000Z", "gb": 1.12, "requests": 3410, "success_rate": 98.9 }, { "start": "2026-10-24T00:00:00.000Z", "gb": 0.874, "requests": 2602, "success_rate": 99.1 }, { "start": "2026-10-25T00:00:00.000Z", "gb": 1.031, "requests": 2950, "success_rate": 98.2 }, { "start": "2026-10-26T00:00:00.000Z", "gb": 1.402, "requests": 4118, "success_rate": 98.6 }, { "start": "2026-10-27T00:00:00.000Z", "gb": 1.288, "requests": 3820, "success_rate": 98.9 }, { "start": "2026-10-28T00:00:00.000Z", "gb": 0.489, "requests": 1442, "success_rate": 98.5 } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/orders": { "get": { "operationId": "listOrders", "summary": "List orders", "tags": [ "Orders" ], "description": "Orders newest first. `type` is `traffic` (bought), `trial`, `bonus` (the first top-up bonus) or `ips` (ISP and datacenter IPs). Traffic orders show `gb_left`; the total of an account's active orders is in [Get the account](https://aeonproxy.com/docs/api/account#get-account).\n\nReference: https://aeonproxy.com/docs/api/orders#list-orders", "parameters": [ { "name": "product", "in": "query", "required": false, "description": "Only one product.", "schema": { "type": "string", "enum": [ "residential", "mobile", "isp", "datacenter" ] } }, { "name": "status", "in": "query", "required": false, "description": "Only one status.", "schema": { "type": "string", "enum": [ "active", "pending", "expired", "cancelled" ] } }, { "name": "limit", "in": "query", "required": false, "description": "Page size.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "How many orders to skip.", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "responses": { "200": { "description": "List orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "product": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "gb_total": { "type": "integer" }, "gb_left": { "type": "number" }, "ip_count": {}, "total_usd": { "type": "number" }, "created_at": { "type": "string" }, "expires_at": {}, "next_due": {}, "auto_renew": {}, "tag": { "type": "string" } } } } } }, "example": { "count": 1, "limit": 50, "offset": 0, "results": [ { "id": 5120, "product": "residential", "type": "traffic", "status": "active", "gb_total": 10, "gb_left": 7.431, "ip_count": null, "total_usd": 29.9, "created_at": "2026-10-24T17:03:12.000Z", "expires_at": null, "next_due": null, "auto_renew": null, "tag": "" } ] } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Get an order", "tags": [ "Orders" ], "description": "One order. ISP and datacenter orders also list their IPs with ports.\n\nReference: https://aeonproxy.com/docs/api/orders#get-order", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order id.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Get an order", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "product": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "gb_total": { "type": "integer" }, "gb_left": { "type": "number" }, "ip_count": {}, "total_usd": { "type": "number" }, "created_at": { "type": "string" }, "expires_at": {}, "next_due": {}, "auto_renew": {}, "tag": { "type": "string" } } }, "example": { "id": 5120, "product": "residential", "type": "traffic", "status": "active", "gb_total": 10, "gb_left": 7.431, "ip_count": null, "total_usd": 29.9, "created_at": "2026-10-24T17:03:12.000Z", "expires_at": null, "next_due": null, "auto_renew": null, "tag": "" } } } }, "401": { "$ref": "#/components/responses/E401" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/traffic/price": { "get": { "operationId": "getPrice", "summary": "Get a price", "tags": [ "Orders" ], "description": "What a purchase would cost right now: the tier rate, the discount that applies and whether the balance covers it. Nothing is charged.\n\nReference: https://aeonproxy.com/docs/api/orders#get-price", "parameters": [ { "name": "product", "in": "query", "required": true, "description": "Which pool: `residential` or `mobile`.", "schema": { "type": "string", "enum": [ "residential", "mobile" ] } }, { "name": "gb", "in": "query", "required": true, "description": "GB to buy.", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "promo_code", "in": "query", "required": false, "description": "A promo code to apply.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a price", "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string" }, "gb": { "type": "integer" }, "rate_usd": { "type": "number" }, "subtotal_usd": { "type": "number" }, "discount": { "type": "object", "properties": { "type": {}, "percent": { "type": "integer" } } }, "total_usd": { "type": "number" }, "balance_usd": { "type": "number" }, "enough_balance": { "type": "boolean" } } }, "example": { "product": "residential", "gb": 10, "rate_usd": 2.99, "subtotal_usd": 29.9, "discount": { "type": null, "percent": 0 }, "total_usd": 29.9, "balance_usd": 42.5, "enough_balance": true } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "429": { "$ref": "#/components/responses/E429" } } } }, "/traffic/purchase": { "post": { "operationId": "buyTraffic", "summary": "Buy traffic", "tags": [ "Orders" ], "description": "Charges the balance and adds the traffic to the product. Send an `Idempotency-Key` header (any unique string up to 64 characters): if the connection drops, send the same request with the same key and you get the first answer back instead of a second purchase. Up to 10 purchases per minute.\n\nReference: https://aeonproxy.com/docs/api/orders#buy-traffic", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string up to 64 characters; a retry with the same key gets the first answer back.", "schema": { "type": "string", "maxLength": 64 } } ], "responses": { "201": { "description": "Buy traffic", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "integer" }, "product": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "gb_total": { "type": "integer" }, "gb_left": { "type": "integer" }, "ip_count": {}, "total_usd": { "type": "number" }, "created_at": { "type": "string" }, "expires_at": {}, "next_due": {}, "auto_renew": {}, "tag": { "type": "string" } } }, "charged_usd": { "type": "number" }, "discount": { "type": "object", "properties": { "type": {}, "percent": { "type": "integer" } } }, "balance_usd": { "type": "number" } } }, "example": { "order": { "id": 5120, "product": "residential", "type": "traffic", "status": "active", "gb_total": 10, "gb_left": 10, "ip_count": null, "total_usd": 29.9, "created_at": "2026-10-24T17:03:12.000Z", "expires_at": null, "next_due": null, "auto_renew": null, "tag": "" }, "charged_usd": 29.9, "discount": { "type": null, "percent": 0 }, "balance_usd": 12.6 } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "429": { "$ref": "#/components/responses/E429" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "product", "gb" ], "properties": { "product": { "type": "string", "enum": [ "residential", "mobile" ], "description": "Which pool: `residential` or `mobile`." }, "gb": { "type": "integer", "minimum": 1, "maximum": 1000, "description": "GB to buy." }, "promo_code": { "type": "string", "description": "A promo code to apply." }, "start_now": { "type": "boolean", "default": false, "description": "Customers in the EU and the UK must send `true`: it asks us to start the service at once, like the checkbox at checkout. If you withdraw within 14 days, you pay for the part already used." } } }, "example": { "product": "residential", "gb": 10 } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "The key from Settings → API in the dashboard (ap_live_…)." }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "The same key, for clients that cannot send a Bearer header." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" } } } } } }, "responses": { "E400": { "description": "invalid_parameter: A parameter is missing or wrong; `param` names it; invalid_json: The body is not a JSON object; invalid_request: An account rule refused the request (the message says which)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "unauthorized: No key, or a key that is not valid any more", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E402": { "description": "insufficient_balance: The balance does not cover a purchase", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "forbidden: The account email is not confirmed yet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "not_found: No such endpoint, or no such object on your account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "conflict: The name is taken, or the Idempotency-Key is busy or was used elsewhere; limit_reached: An account limit, such as 50 sub-users per product", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "rate_limited: Too many requests; wait for `Retry-After` seconds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }