Sub-users API

Separate logins for team members, projects and applications, each with its own traffic limit.

A sub-user is a proxy login of its own on your account's traffic. Give one to each script, server or team member: its usage is counted apart, a limit stops it without touching the others, and its password can be changed without breaking theirs.

limit_gb caps a sub-user at that many GB of your account's traffic; 0 means no limit of its own (it can use everything the account has). When a sub-user reaches its limit the gateway answers 402 for its login. You can have up to 50 sub-users per product. Sub-users are for your own organization: giving access to people outside it counts as resale, which our Terms allow only with our written consent.

List sub-users

GET/api/v1/sub-users

All sub-users, or those of one product.

Query parameters

Name	Type	Description
`product`	residential \| mobile	`residential` or `mobile`. Omit for both.

Request

curl "https://aeonproxy.com/api/v1/sub-users?product=residential" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY"

import os
import requests

r = requests.get(
    "https://aeonproxy.com/api/v1/sub-users?product=residential",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}"},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/sub-users?product=residential", {
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/sub-users?product=residential');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://aeonproxy.com/api/v1/sub-users?product=residential", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 200

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

Errors

Status	Code	When
400	`invalid_parameter`	`product` is not `residential` / `mobile`

Create a sub-user

POST/api/v1/sub-usersIdempotency-Key

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.

Body (JSON)

Name	Type	Description
`product`required	residential \| mobile	Which pool: `residential` or `mobile`.
`name`required	string	Up to 24 characters, unique per product.
`limit_gb`	number	Traffic limit in GB, in steps of 0.1. `0`: no limit of its own. Capped at the traffic you have bought. From 0. Default `0`.

Request

curl -X POST "https://aeonproxy.com/api/v1/sub-users" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY" \
  -H "Idempotency-Key: 5f0c7e9a-2d4b-4f61-9a3e-8b1d2c6e7f40" \
  -H "Content-Type: application/json" \
  -d '{"product":"residential","name":"scraper-eu","limit_gb":5}'

import os
import requests

r = requests.post(
    "https://aeonproxy.com/api/v1/sub-users",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}", "Idempotency-Key": "5f0c7e9a-2d4b-4f61-9a3e-8b1d2c6e7f40"},
    json={"product": "residential", "name": "scraper-eu", "limit_gb": 5},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/sub-users", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
    "Idempotency-Key": "5f0c7e9a-2d4b-4f61-9a3e-8b1d2c6e7f40",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ product: "residential", name: "scraper-eu", limit_gb: 5 }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/sub-users');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
        'Idempotency-Key: 5f0c7e9a-2d4b-4f61-9a3e-8b1d2c6e7f40',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['product' => 'residential', 'name' => 'scraper-eu', 'limit_gb' => 5]),
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{"product":"residential","name":"scraper-eu","limit_gb":5}`)
	req, err := http.NewRequest("POST", "https://aeonproxy.com/api/v1/sub-users", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	req.Header.Set("Idempotency-Key", "5f0c7e9a-2d4b-4f61-9a3e-8b1d2c6e7f40")
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 201

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

Errors

Status	Code	When
400	`invalid_parameter`	`product` is missing or not `residential` / `mobile`
400	`invalid_parameter`	no name, or a negative limit
409	`conflict`	a sub-user with this name exists
409	`limit_reached`	the product already has 50 sub-users

Get a sub-user

GET/api/v1/sub-users/{id}

One sub-user with its login, password, limit and the traffic it has used.

Path parameters

Name	Type	Description
`id`required	integer	The sub-user id from List sub-users.

Request

curl "https://aeonproxy.com/api/v1/sub-users/311" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY"

import os
import requests

r = requests.get(
    "https://aeonproxy.com/api/v1/sub-users/311",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}"},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/sub-users/311", {
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/sub-users/311');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://aeonproxy.com/api/v1/sub-users/311", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 200

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

Errors

Status	Code	When
404	`not_found`	no sub-user with this id on your account

Update a sub-user

PATCH/api/v1/sub-users/{id}

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.

Path parameters

Name	Type	Description
`id`required	integer	The sub-user id from List sub-users.

Body (JSON)

Name	Type	Description
`name`	string	New name, same rules as on create.
`limit_gb`	number	New limit in GB; `0` removes it. From 0.

Request

curl -X PATCH "https://aeonproxy.com/api/v1/sub-users/311" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit_gb":10}'

import os
import requests

r = requests.patch(
    "https://aeonproxy.com/api/v1/sub-users/311",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}"},
    json={"limit_gb": 10},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/sub-users/311", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ limit_gb: 10 }),
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/sub-users/311');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['limit_gb' => 10]),
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	body := strings.NewReader(`{"limit_gb":10}`)
	req, err := http.NewRequest("PATCH", "https://aeonproxy.com/api/v1/sub-users/311", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 200

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

Errors

Status	Code	When
404	`not_found`	no sub-user with this id on your account
409	`conflict`	another sub-user has this name

Delete a sub-user

DELETE/api/v1/sub-users/{id}

Deletes the login: its proxy lines stop working at once. The traffic it used stays used; nothing is refunded to the account.

Path parameters

Name	Type	Description
`id`required	integer	The sub-user id from List sub-users.

Request

curl -X DELETE "https://aeonproxy.com/api/v1/sub-users/311" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY"

import os
import requests

r = requests.delete(
    "https://aeonproxy.com/api/v1/sub-users/311",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}"},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/sub-users/311", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/sub-users/311');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("DELETE", "https://aeonproxy.com/api/v1/sub-users/311", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 200

{
  "id": 311,
  "deleted": true
}

Errors

Status	Code	When
404	`not_found`	no sub-user with this id on your account

Rotate a sub-user password

POST/api/v1/sub-users/{id}/password

Gives the sub-user a new password; the old one stops working at once.

Path parameters

Name	Type	Description
`id`required	integer	The sub-user id from List sub-users.

Request

curl -X POST "https://aeonproxy.com/api/v1/sub-users/311/password" \
  -H "Authorization: Bearer $AEONPROXY_API_KEY"

import os
import requests

r = requests.post(
    "https://aeonproxy.com/api/v1/sub-users/311/password",
    headers={"Authorization": f"Bearer {os.environ['AEONPROXY_API_KEY']}"},
    timeout=30,
)
data = r.json()
if not r.ok:
    raise SystemExit(data["error"]["message"])
print(data)

// Node.js 18+, as an ES module (.mjs)
const res = await fetch("https://aeonproxy.com/api/v1/sub-users/311/password", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AEONPROXY_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error.message);
console.log(data);

<?php
$ch = curl_init('https://aeonproxy.com/api/v1/sub-users/311/password');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AEONPROXY_API_KEY'),
    ],
    CURLOPT_POSTFIELDS => '',
    CURLOPT_RETURNTRANSFER => true,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$data = json_decode($body, true);
if ($status >= 400) {
    fwrite(STDERR, $data['error']['message'] . PHP_EOL);
    exit(1);
}
print_r($data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("POST", "https://aeonproxy.com/api/v1/sub-users/311/password", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AEONPROXY_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status)
	fmt.Println(string(out))
}

Response 200

{
  "id": 311,
  "username": "ap_7f3c",
  "password": "Qd2hN7yV4cPa"
}

Errors

Status	Code	When
404	`not_found`	no sub-user with this id on your account

Example: One sub-user per server

Each machine gets its own login with a 20 GB cap, and its own proxy lines.

import os, requests

API = "https://aeonproxy.com/api/v1"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['AEONPROXY_API_KEY']}"

for host in ["worker-1", "worker-2", "worker-3"]:
    sub = s.post(f"{API}/sub-users", json={"product": "residential", "name": host, "limit_gb": 20}, timeout=30).json()
    lines = s.post(f"{API}/proxy-list", json={"product": "residential", "sub_user_id": sub["id"], "count": 50}, timeout=30).json()
    print(host, sub["username"], len(lines["results"]), "lines")

Your API key is already in the dashboard.

Create an account API overview

Sub-users API

List sub-users

Query parameters

Request

Response 200

Errors

Create a sub-user

Body (JSON)

Request

Response 201

Errors

Get a sub-user

Path parameters

Request

Response 200

Errors

Update a sub-user

Path parameters

Body (JSON)

Request

Response 200

Errors

Delete a sub-user

Path parameters

Request

Response 200

Errors

Rotate a sub-user password

Path parameters

Request

Response 200

Errors

Example: One sub-user per server

See also

Your API key is already in the dashboard.