API models

Every object the API returns, with the type and meaning of each field.

Answers are JSON objects with snake_case names. Traffic is in GB (10⁹ bytes), money in US dollars as numbers, times in ISO 8601 UTC. A field documented as null-able is always present, with null when it has no value. New fields may be added to any object within v1: ignore the ones you do not know.

Account

What Get the account returns.

Field	Type	Description
`id`	integer	Account id.
`email`	string	Sign-in email.
`created_at`	string (ISO 8601, UTC)	When the account was created.
`balance_usd`	number	Wallet balance in US dollars.
`traffic`	object	`residential` and `mobile`, each a Traffic object.
`sub_users`	object	Number of sub-users per product.
`active_orders`	integer	Orders with the status `active`.

{
  "id": 1042,
  "email": "[email protected]",
  "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
}

Returned by: Get the account

Traffic

Traffic of one product, in GB (10⁹ bytes): everything bought and granted that is still active.

Field	Type	Description
`gb_total`	number	Traffic of the active orders.
`gb_used`	number	Used of it.
`gb_left`	number	What the proxies can still carry.

{
  "gb_total": 25,
  "gb_used": 6.204,
  "gb_left": 18.796
}

Returned by: Get the account, Get proxy credentials

Credentials

The main proxy login of one product and where to connect.

Field	Type	Description
`product`	string	`residential` or `mobile`.
`host`	string	Gateway host.
`port_http`	integer	Port for HTTP and HTTPS (CONNECT).
`port_socks5`	integer	Port for SOCKS5, TCP and UDP.
`username`	string	The login, before any targeting keys.
`password`	string	Its password.
`traffic`	object	A Traffic object.

{
  "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
  }
}

Returned by: Get proxy credentials

Country

An item of List countries.

Field	Type	Description
`code`	string	ISO 3166-1 alpha-2 code in lower case: the `country` parameter and the `-cc-` key.
`name`	string	English name.

{
  "code": "us",
  "name": "United States"
}

Returned by: List countries

Location

A region, city, ISP or carrier of one country.

Field	Type	Description
`name`	string	The name in our network's list, lower case for regions and cities.
`slug`	string	Letters and digits of the name: the value of `-st-`, `-city-`, `-isp-` or `-car-` in a login.

{
  "name": "california",
  "slug": "california"
}

Returned by: List regions, List cities, List ISPs and carriers

Proxy line

An item of Generate a proxy list.

Field	Type	Description
`host`	string	Gateway host.
`port`	integer	The port of the chosen protocol.
`username`	string	The login with its targeting and session keys.
`password`	string	The password.
`proxy`	string	All four joined in the requested `format`.

{
  "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"
}

Returned by: Generate a proxy list, Download a proxy list

Preset

Saved generator settings, shared with the dashboard.

Field	Type	Description
`id`	integer	Preset id, for `preset_id`.
`product`	string	`residential` or `mobile`.
`name`	string	Its name.
`country`	string or null	Country code, or `null` for any.
`region`	string or null	Region name.
`city`	string or null	City name.
`isp`	string or null	ISP name (residential).
`carrier`	string or null	Carrier name (mobile).
`session`	string	`sticky` or `rotating`.
`ttl`	integer	Sticky minutes.
`protocol`	string	`http` or `socks5`.
`count`	integer	Lines to generate.

{
  "id": 57,
  "product": "residential",
  "name": "US sticky 30m",
  "country": "us",
  "region": "new york",
  "city": null,
  "isp": null,
  "carrier": null,
  "session": "sticky",
  "ttl": 30,
  "protocol": "http",
  "count": 50
}

Returned by: List presets, Save a preset

Proxy check

An item of Check proxies.

Field	Type	Description
`proxy`	string	The line as sent.
`ok`	boolean	Whether the request went through.
`status`	string	HTTP status of the answer, or what failed (`407 proxy auth`, `timeout`, …).
`ms`	integer or null	Time of the whole request.
`exit_ip`	string or null	The IP the site saw.
`country`	string or null	Its country code.
`country_name`	string or null	Its country.
`udp`	boolean or null	SOCKS5 only: whether a UDP association worked.

{
  "proxy": "gate.aeonproxy.com:7000:ap_u1a2b-cc-de:Xr7pQ2mK9sLd",
  "ok": true,
  "status": "200",
  "ms": 412,
  "exit_ip": "91.64.18.203",
  "country": "de",
  "country_name": "Germany",
  "udp": null
}

Returned by: Check proxies

Sub-user

A proxy login of its own on the account's traffic.

Field	Type	Description
`id`	integer	Sub-user id.
`product`	string	`residential` or `mobile`.
`name`	string	Its name: lower case, letters, digits and dashes.
`username`	string	Its proxy login.
`password`	string	Its proxy password.
`limit_gb`	number	Its traffic limit; `0` means none of its own.
`used_gb`	number	Traffic it has used.
`status`	string	`active` or `limit_reached`.
`created_at`	string (ISO 8601, UTC)	When it was created.

{
  "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"
}

Returned by: List sub-users, Create a sub-user, Get a sub-user, Update a sub-user

Usage

What Get usage returns.

Field	Type	Description
`product`	string	`residential` or `mobile`.
`period`	string	`24h`, `7d` or `30d`.
`granularity`	string	`hour` or `day`.
`from`	string (ISO 8601, UTC)	Start of the first point.
`to`	string (ISO 8601, UTC)	Now.
`totals`	object	`gb`, `requests` and `success_rate` of the whole period.
`series`	array	One point per hour or day: `start`, `gb`, `requests`, `success_rate` (a percentage, `null` without requests).

{
  "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-23T00:00:00.000Z",
      "gb": 1.12,
      "requests": 3410,
      "success_rate": 98.9
    }
  ]
}

Returned by: Get usage

Product

An item of List products and prices. Traffic products have tiers; per-IP products have price_usd.

Field	Type	Description
`id`	string	`residential`, `mobile`, `isp` or `datacenter`.
`name`	string	Product name.
`unit`	string	`gb` or `ip_month`.
`on_sale`	boolean	Whether it can be bought now.
`traffic_expires`	boolean	Traffic products: `false`, bought traffic never expires.
`tiers`	array	`from_gb` and `rate_usd` of each tier; the rate of the tier the purchase falls in applies to all of it.
`min_gb`	integer	Smallest purchase.
`max_gb_per_purchase`	integer	Largest single purchase.

{
  "id": "residential",
  "name": "Residential proxies",
  "unit": "gb",
  "on_sale": true,
  "traffic_expires": false,
  "tiers": [
    {
      "from_gb": 1,
      "rate_usd": 3.49
    },
    {
      "from_gb": 10,
      "rate_usd": 2.99
    },
    {
      "from_gb": 50,
      "rate_usd": 2.69
    },
    {
      "from_gb": 100,
      "rate_usd": 2.39
    },
    {
      "from_gb": 250,
      "rate_usd": 2.09
    },
    {
      "from_gb": 500,
      "rate_usd": 1.89
    },
    {
      "from_gb": 1000,
      "rate_usd": 1.69
    }
  ],
  "min_gb": 1,
  "max_gb_per_purchase": 1000
}

Returned by: List products and prices

Order

A purchase, a trial or a bonus. ISP and datacenter orders also carry username, password and ips.

Field	Type	Description
`id`	integer	Order id.
`product`	string	Product id.
`type`	string	`traffic`, `trial`, `bonus` or `ips`.
`status`	string	`active`, `pending`, `expired` or `cancelled`.
`gb_total`	number or null	Traffic orders: GB in the order.
`gb_left`	number or null	Traffic orders: GB left of it.
`ip_count`	integer or null	Per-IP orders: number of IPs.
`total_usd`	number	What was charged.
`created_at`	string (ISO 8601, UTC)	When it started.
`expires_at`	string (ISO 8601, UTC) or null	Trials: when they end.
`next_due`	string (ISO 8601, UTC) or null	Per-IP orders: the next renewal.
`auto_renew`	boolean or null	Per-IP orders: renewal on or off.
`tag`	string	Your label.

{
  "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": ""
}

Returned by: List orders, Get an order, Update an order, Buy traffic

Price quote

What Get a price returns.

Field	Type	Description
`product`	string	Product id.
`gb`	integer	GB asked for.
`rate_usd`	number	Per-GB rate of the tier.
`subtotal_usd`	number	Before the discount.
`discount`	object	`type` (`promo`, `loyalty` or `null`) and `percent`.
`total_usd`	number	What a purchase would charge.
`balance_usd`	number	The balance now.
`enough_balance`	boolean	Whether it covers the total.

{
  "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
}

Returned by: Get a price

Transaction

An item of List transactions.

Field	Type	Description
`id`	integer	Transaction id.
`type`	string	`deposit`, `charge`, `refund`, `coupon`, `bonus`, `commission` or `adjustment`.
`amount_usd`	number	Signed amount: charges are negative.
`status`	string	`paid` (counts in the balance), `pending`, `failed` or `held`.
`method`	string	How it was paid or what it was.
`invoice_number`	integer or null	Its invoice, if any.
`created_at`	string (ISO 8601, UTC)	When it was made.

{
  "id": 3301,
  "type": "charge",
  "amount_usd": -29.9,
  "status": "paid",
  "method": "Wallet balance",
  "invoice_number": 101962,
  "created_at": "2026-10-24T17:03:12.000Z"
}

Returned by: List transactions

Invoice

An invoice with its lines.

Field	Type	Description
`number`	integer	Invoice number.
`type`	string	What it is for (`deposit`, `traffic`, `order`, …).
`description`	string	One line about it.
`items`	array	`label` and `amount_usd` of each line.
`total_usd`	number	Total.
`status`	string	`paid`, `unpaid` or `pending`.
`method`	string	How it was paid.
`issued_at`	string (ISO 8601, UTC)	Issue date.
`order_id`	integer or null	The order it belongs to, if any.

{
  "number": 101962,
  "type": "traffic",
  "description": "Residential traffic · 10 GB",
  "items": [
    {
      "label": "10 GB × $2.99",
      "amount_usd": 29.9
    }
  ],
  "total_usd": 29.9,
  "status": "paid",
  "method": "Wallet balance",
  "issued_at": "2026-10-24T17:03:12.000Z",
  "order_id": 5120
}

Returned by: List invoices, Get an invoice

Notification

An item of List notifications.

Field	Type	Description
`id`	integer	Notification id.
`kind`	string	Category (`security`, `gift`, `traffic`, …).
`title`	string	Title.
`body`	string	Text.
`link`	string or null	The dashboard page about it.
`unread`	boolean	Not read in the dashboard yet.
`created_at`	string (ISO 8601, UTC)	When it was sent.

{
  "id": 812,
  "kind": "gift",
  "title": "Coupon applied",
  "body": "$5.00 was added to your balance.",
  "link": "https://aeonproxy.com/dashboard/wallet",
  "unread": true,
  "created_at": "2026-10-27T15:40:02.000Z"
}

Returned by: List notifications

Referral earnings

What Get referral earnings returns.

Field	Type	Description
`code`	string	Your referral code.
`link`	string	Your referral link.
`commission_percent`	integer	Share of each referred purchase.
`referrals`	integer	Accounts that signed up with your code.
`earned_usd`	number	All commissions.
`unpaid_usd`	number	Not paid out yet.
`payable_usd`	number	Past the hold period, can be requested.
`hold_days`	integer	Days before a commission becomes payable.
`payouts`	array	`id`, `amount_usd`, `method`, `status` and `created_at` of each payout.

{
  "code": "ap-3f9c2",
  "link": "https://aeonproxy.com/?ref=ap-3f9c2",
  "commission_percent": 10,
  "referrals": 4,
  "earned_usd": 18.6,
  "unpaid_usd": 6.2,
  "payable_usd": 4.1,
  "hold_days": 14,
  "payouts": [
    {
      "id": 21,
      "amount_usd": 12.4,
      "method": "balance",
      "status": "paid",
      "created_at": "2026-10-19T11:05:00.000Z"
    }
  ]
}

Returned by: Get referral earnings

Error

The body of every failed request; see Errors.

Field	Type	Description
`error`	object	`code` (stable, for your code), `message` (for people) and `param` (the parameter at fault, when there is one).

{
  "error": {
    "code": "invalid_parameter",
    "message": "product must be residential or mobile.",
    "param": "product"
  }
}

Your API key is already in the dashboard.

Create an account API overview