Обзор#
API Proxonym позволяет управлять аккаунтом из кода: получать балансы и тарифы, выгружать данные о расходе, скачивать списки прокси, редактировать белый список IP и управлять субпользователями. Google SERP API работает на отдельном хосте и возвращает структурированные результаты поиска в формате JSON.
Базовый URL
https://api.proxonym.com/v1Пути в этом справочнике указаны относительно базового URL. Все запросы выполняются по HTTPS. У SERP API собственный базовый URL — https://serp.proxonym.com/v1.
Описание в формате OpenAPI
API аккаунта также описан в формате OpenAPI 3.1 по адресу /docs/api/openapi.json — это описание подходит для генераторов клиентов, инструментов для работы с API и ИИ-агентов.
Версионирование
Мажорная версия входит в путь. Изменения, нарушающие совместимость, выходят только в новой версии. В рамках v1 могут появляться новые эндпоинты, необязательные параметры и поля ответа, поэтому пишите клиенты так, чтобы они игнорировали незнакомые поля.
Соглашения
- Формат: ответы приходят в JSON в кодировке UTF-8 с заголовком
Content-Type: application/json, кроме списков прокси, запрошенных сformat=txt. Тело запроса отправляйте в JSON с заголовкомContent-Type: application/json. - Коды ответа:
200при успехе и201при создании ресурса. Ошибки описаны в разделе «Ошибки». - Временные метки: ISO 8601 в UTC, например
2026-10-01T09:30:00Z. Параметры дат принимают полную временную метку или дату, например2026-09-24, — она трактуется как полночь по UTC. - Трафик: в гигабайтах, в виде десятичного числа, например
17.836. - Идентификаторы: строки с префиксом типа, например
su_3k9x2m7qдля субпользователя. Обращайтесь с ними как с непрозрачными значениями. - Отсутствующие значения:
null, например"expires_at": nullу бессрочного пакета. - Продукты:
residential,mobile,unlimited,isp,datacenter,dedicatedиserp.
Эндпоинты
| Метод | Путь | Описание |
|---|---|---|
GET | /account | Аккаунт, балансы ГБ и активные тарифы |
GET | /usage | Расход одного продукта за период |
GET | /proxies/{product} | Список прокси дата-центров, ISP-прокси или выделенных прокси |
GET | /whitelist | Получить IP из белого списка |
POST | /whitelist | Добавить IP в белый список |
DELETE | /whitelist/{ip} | Удалить IP из белого списка |
GET | /sub-users | Получить список субпользователей |
POST | /sub-users | Создать субпользователя |
PATCH | /sub-users/{id} | Изменить субпользователя |
DELETE | /sub-users/{id} | Удалить субпользователя |
GET | https://serp.proxonym.com/v1/search | Выдача Google в виде структурированного JSON |
Первый вызов
Создайте API-ключ в личном кабинете, экспортируйте его в переменную окружения, а затем запросите данные аккаунта:
export PROXONYM_API_KEY="your_api_key"
curl https://api.proxonym.com/v1/account \
-H "Authorization: Bearer $PROXONYM_API_KEY"Примеры в этом справочнике берут API-ключ аккаунта из $PROXONYM_API_KEY, а ключ SERP API — из $PROXONYM_SERP_KEY.
Аутентификация#
API аккаунта аутентифицирует каждый запрос по API-ключу, который передаётся как bearer-токен в заголовке Authorization:
Authorization: Bearer <API_KEY>Ключи создаются и отзываются в личном кабинете. Ключ действует на весь аккаунт: с ним можно читать расход, скачивать учётные данные прокси и управлять субпользователями. Запрос с отсутствующим, неверно сформированным или отозванным ключом завершается ошибкой 401:
curl -i https://api.proxonym.com/v1/account \
-H "Authorization: Bearer wrong_key"HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing, malformed or revoked."
}
}Храните ключи в секрете
- Вызывайте API только со своих серверов. Никогда не размещайте ключ на веб-странице, в мобильном приложении или публичном репозитории.
- Загружайте ключи из переменных окружения или менеджера секретов и не допускайте их попадания в логи.
- Используйте отдельный ключ для каждого сервиса, чтобы можно было отозвать один, не затрагивая остальные.
- API-ключи — это не учётные данные прокси. Для подключения к прокси используются ваши имя пользователя и пароль прокси; см. аутентификацию прокси.
Ротация ключей
- Создайте новый ключ в личном кабинете.
- Разверните его во всех сервисах, которые вызывают API.
- Убедитесь, что вызовы с новым ключом проходят успешно, затем отзовите старый.
Меняйте ключи по расписанию и немедленно отзывайте ключ, если он мог утечь. Запросы с отозванным ключом завершаются ошибкой 401.
Ключ SERP API
SERP API принимает ключ в заголовке X-API-Key, а не Authorization. См. раздел «SERP API».
Лимиты запросов#
API аккаунта принимает 60 запросов в минуту. Каждый ответ сообщает, сколько запросов у вас осталось:
| Заголовок | Описание |
|---|---|
X-RateLimit-Limit | Разрешённое число запросов в минуту: 60 |
X-RateLimit-Remaining | Сколько запросов осталось в текущем окне |
Retry-After | Только в ответах 429: через сколько секунд можно отправить следующий запрос |
При превышении лимита API отвечает 429:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 18
{
"error": {
"code": "rate_limited",
"message": "Rate limit of 60 requests per minute exceeded. Retry after 18 seconds."
}
}Использование SERP API учитывается иначе — по месячному объёму запросов вашего тарифа; см. раздел «SERP API».
Обработка 429
Подождите столько секунд, сколько указано в Retry-After, и повторите запрос. Чтобы не превышать лимит:
- Кэшируйте редко меняющиеся данные, например списки прокси и белый список.
- Запрашивайте расход раз в несколько минут, а не каждые несколько секунд. Минимальная детализация — один час.
- Растягивайте пакетные операции, например создание большого числа субпользователей, на несколько минут.
import os
import time
import requests
API = "https://api.proxonym.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"}
def api_get(path, params=None, attempts=5):
for _ in range(attempts):
r = requests.get(API + path, headers=HEADERS, params=params, timeout=30)
if r.status_code != 429:
r.raise_for_status()
return r.json()
time.sleep(int(r.headers.get("Retry-After", "5")))
raise RuntimeError(f"{path}: still rate limited after {attempts} attempts")
print(api_get("/usage", {"product": "residential", "granularity": "day"}))Ошибки#
Ошибки возвращаются со стандартными кодами ответа HTTP и телом JSON, в котором есть стабильное машиночитаемое поле code и понятное человеку поле message:
{
"error": {
"code": "invalid_api_key",
"message": "The API key is missing, malformed or revoked."
}
}Стройте логику обработки на code и никогда — на message: формулировки сообщений могут меняться, а коды остаются стабильными.
| Статус | Код | Значение | Что делать |
|---|---|---|---|
400 | invalid_request | Запрос сформирован неверно: невалидный JSON, не указан обязательный параметр или значение имеет неверный тип | Исправьте запрос. Повтор не поможет |
401 | invalid_api_key | API-ключ отсутствует, сформирован неверно или отозван | Проверьте заголовок и ключ |
403 | product_not_active, quota_exceeded | Ключ действителен, но у продукта нет активного тарифа или в тарифе SERP закончились запросы | Купите или продлите тариф |
404 | not_found | Путь, продукт, ID субпользователя или IP в белом списке не существует | Проверьте путь и ID |
409 | already_exists | IP уже есть в белом списке, или это название уже занято другим субпользователем | Используйте существующий ресурс или выберите другое значение |
422 | validation_failed, whitelist_full | Значение имеет правильный формат, но не принимается (например, недопустимый IP, неизвестный продукт или слишком длинный диапазон дат), либо заняты все слоты белого списка | Исправьте значение или сначала удалите IP из белого списка |
429 | rate_limited | Более 60 запросов за минуту | Подождите указанное в Retry-After число секунд и повторите запрос |
500 | internal_error | Непредвиденная ошибка на нашей стороне | Повторите запрос с экспоненциальной задержкой |
Повторять без изменений стоит только запросы, получившие 429 или 500. Если ошибка 500 не исчезает, запишите эндпоинт, время запроса и полное тело ошибки: на тарифе с выделенными прокси дата-центров отправьте их нашей команде в тикете.
Аккаунт#
Получайте данные аккаунта, балансы ГБ и активные тарифы.
Получение данных аккаунта
GET /account
Возвращает аккаунт, его балансы ГБ и все активные тарифы. Истёкшие тарифы не включаются.
Параметры
Нет.
Пример запроса
curl https://api.proxonym.com/v1/account \
-H "Authorization: Bearer $PROXONYM_API_KEY"Пример ответа
{
"id": "acc_7d3f9k2m",
"email": "you@company.example",
"created_at": "2026-03-14T08:21:47Z",
"credit_usd": 245.5,
"balances": {
"residential": {
"gb_remaining": 37.836,
"expires_at": "2026-10-12T14:03:51Z",
"packs": [
{
"gb_purchased": 40,
"gb_remaining": 17.836,
"purchased_at": "2026-09-12T14:03:51Z",
"expires_at": "2026-10-12T14:03:51Z"
},
{
"gb_purchased": 20,
"gb_remaining": 20.0,
"purchased_at": "2026-08-02T16:40:55Z",
"expires_at": null
}
]
},
"datacenter": {
"gb_remaining": 687.52,
"expires_at": "2026-10-18T09:12:40Z"
}
},
"plans": [
{
"id": "pl_4k8d2pqm",
"product": "unlimited",
"bandwidth_mbps": 200,
"gateway": "use.unl.proxonym.com",
"udp": false,
"started_at": "2026-09-25T10:00:00Z",
"expires_at": "2026-10-02T10:00:00Z"
},
{
"id": "pl_3n7q1wza",
"product": "datacenter",
"ips": 1000,
"bandwidth_gb": 1000,
"started_at": "2026-09-18T09:12:40Z",
"expires_at": "2026-10-18T09:12:40Z"
},
{
"id": "pl_6t2r9exb",
"product": "isp",
"ips": 20,
"started_at": "2026-09-20T15:30:00Z",
"expires_at": "2026-10-20T15:30:00Z"
},
{
"id": "pl_2h5j8kvc",
"product": "serp",
"requests_limit": 100000,
"requests_used": 41827,
"started_at": "2026-09-08T11:45:19Z",
"expires_at": "2026-10-08T11:45:19Z"
}
]
}Поля ответа
| Поле | Тип | Описание |
|---|---|---|
id | string | ID аккаунта |
email | string | Адрес электронной почты аккаунта |
created_at | string | Время создания аккаунта |
credit_usd | number | Баланс аккаунта в долларах США, доступный для покупки тарифов. Пополнения и бонусные средства зачисляются на него |
balances | object | Балансы ГБ, где ключ — продукт: residential (общий с мобильными прокси) и datacenter (месячный объём трафика). Продукты без баланса не включаются |
balances.{product}.gb_remaining | number или null | Остаток ГБ. null на уровне дата-центров «Без ограничений» |
balances.{product}.expires_at | string или null | Ближайшая дата истечения трафика в этом балансе. null, если весь трафик бессрочный |
balances.residential.packs[] | array | По одной записи на каждый пакет ГБ с остатком трафика: gb_purchased, gb_remaining, purchased_at и expires_at (у бессрочных пакетов — null) |
plans[] | array | Активные тарифы. У каждого тарифа есть id, product, status (active или provisioning, пока готовятся статические IP), started_at и expires_at |
plans[].bandwidth_mbps, gateway, udp | integer, string, boolean | Безлимитные резидентные прокси: уровень скорости, сервер шлюза и признак активной опции UDP |
plans[].ips | integer | ISP, дата-центры и выделенные прокси: количество IP |
plans[].bandwidth_gb | integer или null | Дата-центры: месячный объём трафика в ГБ, null на уровне «Без ограничений» |
plans[].requests_limit, requests_used | integer | SERP API: число запросов, включённых в тариф, и число уже использованных запросов |
Мобильный трафик списывается с резидентного баланса, поэтому отдельного баланса mobile нет. Резидентные пакеты ГБ отображаются в balances, а не в plans. Тарифы никогда не продлеваются автоматически: сравнивайте expires_at с текущим временем, чтобы решить, когда продлевать.
Пример: предупреждение о низком балансе
import os
import requests
r = requests.get(
"https://api.proxonym.com/v1/account",
headers={"Authorization": f"Bearer {os.environ['PROXONYM_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
residential = r.json()["balances"].get("residential")
if residential is None or residential["gb_remaining"] < 5:
left = residential["gb_remaining"] if residential else 0
print(f"Residential balance is low: {left:.1f} GB left. Top up before jobs fail with 402.")Расход#
Узнавайте, сколько трафика или запросов SERP вы израсходовали за период.
Получение расхода
GET /usage
Возвращает расход одного продукта за период: итог и временной ряд.
Параметры
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
product | string, в строке запроса | Да | residential, mobile, unlimited, isp, datacenter, dedicated или serp |
from | string, в строке запроса | Нет | Начало периода включительно: дата или временная метка ISO 8601 в UTC. По умолчанию — за 7 дней до to |
to | string, в строке запроса | Нет | Конец периода (не включительно). По умолчанию — текущий момент |
granularity | string, в строке запроса | Нет | day (по умолчанию) или hour. Интервалы выравниваются по UTC |
Период может охватывать до 366 дней при детализации day и до 31 дня при hour. Более длинный период или from позже to возвращает 422 с validation_failed. Расход мобильных прокси показывается отдельно, но списывается с резидентного баланса.
Пример запроса
curl -G https://api.proxonym.com/v1/usage \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-d product=residential \
-d from=2026-09-24 \
-d to=2026-10-01 \
-d granularity=dayПример ответа
{
"product": "residential",
"granularity": "day",
"from": "2026-09-24T00:00:00Z",
"to": "2026-10-01T00:00:00Z",
"total": {
"traffic_gb": 9.964
},
"series": [
{ "timestamp": "2026-09-24T00:00:00Z", "traffic_gb": 1.204 },
{ "timestamp": "2026-09-25T00:00:00Z", "traffic_gb": 1.587 },
{ "timestamp": "2026-09-26T00:00:00Z", "traffic_gb": 0.932 },
{ "timestamp": "2026-09-27T00:00:00Z", "traffic_gb": 1.411 },
{ "timestamp": "2026-09-28T00:00:00Z", "traffic_gb": 1.876 },
{ "timestamp": "2026-09-29T00:00:00Z", "traffic_gb": 1.309 },
{ "timestamp": "2026-09-30T00:00:00Z", "traffic_gb": 1.645 }
]
}Поля ответа
| Поле | Тип | Описание |
|---|---|---|
product, granularity | string | Значения, использованные в запросе |
from, to | string | Итоговый период в виде временных меток UTC |
total.traffic_gb | number | Трафик за период в ГБ. Только для прокси-продуктов |
total.requests | integer | Запросы SERP API за период. Только для serp |
series[] | array | По одной точке на интервал в хронологическом порядке. Для интервалов без расхода возвращается 0 |
series[].timestamp | string | Начало интервала |
series[].traffic_gb или series[].requests | number или integer | Расход за интервал в тех же единицах, что и total |
Для serp итоги и точки считаются в запросах, а не в ГБ. Почасовой запрос, например ?product=serp&from=2026-09-30T00:00:00Z&to=2026-09-30T03:00:00Z&granularity=hour, возвращает:
{
"product": "serp",
"granularity": "hour",
"from": "2026-09-30T00:00:00Z",
"to": "2026-09-30T03:00:00Z",
"total": {
"requests": 1854
},
"series": [
{ "timestamp": "2026-09-30T00:00:00Z", "requests": 612 },
{ "timestamp": "2026-09-30T01:00:00Z", "requests": 587 },
{ "timestamp": "2026-09-30T02:00:00Z", "requests": 655 }
]
}Списки прокси#
Скачивайте прокси, закреплённые за вашими статическими тарифами. У резидентных, мобильных и безлимитных резидентных прокси списка нет: к ним подключаются через шлюз, описанный в разделе «Эндпоинты и порты».
Получение списка прокси
GET /proxies/{product}
Возвращает все прокси ваших активных тарифов по одному продукту — в JSON или обычным текстом, по одному прокси в строке.
Параметры
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
product | string, в пути | Да | datacenter, isp или dedicated |
format | string, в строке запроса | Нет | json (по умолчанию) или txt |
country | string, в строке запроса | Нет | Вернуть только прокси в этой стране: код ISO 3166-1 alpha-2 в нижнем регистре, например us |
Пример запроса
curl https://api.proxonym.com/v1/proxies/isp \
-H "Authorization: Bearer $PROXONYM_API_KEY"Пример ответа
Сокращено до трёх записей; count — полное количество.
{
"product": "isp",
"count": 20,
"proxies": [
{
"ip": "198.51.100.61",
"port": 6200,
"username": "isp_k8w2m4",
"password": "Tz6pW1qR8nVb3xYc",
"country": "us",
"location": "New York",
"expires_at": "2026-10-20T15:30:00Z"
},
{
"ip": "198.51.100.62",
"port": 6200,
"username": "isp_k8w2m4",
"password": "Tz6pW1qR8nVb3xYc",
"country": "us",
"location": "New York",
"expires_at": "2026-10-20T15:30:00Z"
},
{
"ip": "198.51.100.63",
"port": 6200,
"username": "isp_k8w2m4",
"password": "Tz6pW1qR8nVb3xYc",
"country": "us",
"location": "New York",
"expires_at": "2026-10-20T15:30:00Z"
}
]
}Текстовый формат
С format=txt ответ приходит в формате text/plain, по одному прокси в строке: ip:port для дата-центров (порт — это HTTP-порт) и ip:port:username:password для ISP-прокси и выделенных прокси.
curl -G https://api.proxonym.com/v1/proxies/datacenter \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-d format=txt \
-d country=us198.51.100.23:3129
198.51.100.87:3129
198.51.100.142:3129Поля прокси
| Поле | Продукты | Описание |
|---|---|---|
ip | Все | IP-адрес прокси |
port | ISP, выделенные | Порт для HTTP и SOCKS5 |
http_port, socks5_port | Дата-центр | Порт HTTP 3129 и порт SOCKS5 1081 |
username, password | ISP, выделенные | Учётные данные этого прокси |
country | Все | Страна IP: код ISO 3166-1 alpha-2 в нижнем регистре |
location | ISP | Город или пул провайдера, например New York или Comcast pool |
expires_at | ISP, выделенные | Окончание срока действия этого IP |
Запись для дата-центров в JSON выглядит так: {"ip": "198.51.100.23", "http_port": 3129, "socks5_port": 1081, "country": "us"}. Если у продукта нет активного тарифа, API возвращает 403 с product_not_active. Для продукта без списка, например residential, возвращается 404:
{
"error": {
"code": "not_found",
"message": "No proxy list for product residential. Lists exist for datacenter, isp and dedicated."
}
}Белый список#
Белый список позволяет машинам подключаться к вашим общим прокси дата-центров без учётных данных. Каждый тариф на общие прокси дата-центров включает 3 слота, а записи действуют для всех ваших IP дата-центров. Подробнее — в разделе документации «Белый список IP».
Получение IP из белого списка
GET /whitelist
Параметры
Нет.
Пример запроса
curl https://api.proxonym.com/v1/whitelist \
-H "Authorization: Bearer $PROXONYM_API_KEY"Пример ответа
{
"limit": 3,
"ips": [
{ "ip": "192.0.2.10", "created_at": "2026-09-18T09:20:11Z" },
{ "ip": "192.0.2.57", "created_at": "2026-09-22T17:02:45Z" }
]
}limit — число слотов в вашем аккаунте, а ips содержит записи, от самой старой к самой новой.
Добавление IP
POST /whitelist
Параметры
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
ip | string, в теле запроса | Да | Публичный IP-адрес машины, которая будет подключаться, например 192.0.2.44 |
Пример запроса
curl -X POST https://api.proxonym.com/v1/whitelist \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ip": "192.0.2.44"}'Пример ответа
Код ответа 201:
{
"ip": "192.0.2.44",
"created_at": "2026-10-01T09:30:00Z"
}Для IP, который уже есть в списке, возвращается 409 с already_exists, а для недопустимого адреса — 422 с validation_failed. Если заняты все слоты, API возвращает 422:
{
"error": {
"code": "whitelist_full",
"message": "All 3 whitelist slots are in use. Remove an IP before adding another."
}
}Удаление IP
DELETE /whitelist/{ip}
Параметры
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
ip | string, в пути | Да | IP из белого списка, который нужно удалить |
Пример запроса
curl -X DELETE https://api.proxonym.com/v1/whitelist/192.0.2.10 \
-H "Authorization: Bearer $PROXONYM_API_KEY"Пример ответа
{
"ip": "192.0.2.10",
"deleted": true
}После этого запросы с этого IP без учётных данных завершаются ошибкой 407. Для IP, которого нет в списке, возвращается 404 с not_found.
Субпользователи#
Субпользователи — это дополнительные учётные данные прокси в вашем аккаунте, у каждого из которых может быть свой лимит трафика. Их трафик списывается с баланса аккаунта. Подробнее — в разделе документации «Субпользователи».
Объект субпользователя
{
"id": "su_3k9x2m7q",
"name": "price-monitor",
"username": "sub_k3v9q2xd",
"password": "Qm7vT2xK9pLr4sWz",
"traffic_limit_gb": 25,
"traffic_used_gb": 6.412,
"status": "active",
"created_at": "2026-09-14T08:05:22Z"
}| Поле | Тип | Описание |
|---|---|---|
id | string | ID субпользователя, используется в путях API |
name | string | Ваше название для субпользователя, уникальное в пределах аккаунта |
username | string | Имя пользователя прокси, генерируется автоматически. Принимает те же параметры, что и ваше основное имя пользователя, например sub_k3v9q2xd-country-us-session-a7k2 |
password | string | Пароль прокси, генерируется автоматически |
traffic_limit_gb | number или null | Максимальный трафик в ГБ. null — лимита нет, трафик ограничен только балансом аккаунта |
traffic_used_gb | number | Израсходованный трафик в ГБ |
status | string | active или disabled. Отключённым субпользователям прокси отвечает 407 |
created_at | string | Время создания субпользователя |
Когда traffic_used_gb достигает traffic_limit_gb, запросы субпользователя завершаются ошибкой 402, пока вы не повысите лимит.
Получение списка субпользователей
GET /sub-users
Параметры
Нет.
Пример запроса
curl https://api.proxonym.com/v1/sub-users \
-H "Authorization: Bearer $PROXONYM_API_KEY"Пример ответа
{
"sub_users": [
{
"id": "su_3k9x2m7q",
"name": "price-monitor",
"username": "sub_k3v9q2xd",
"password": "Qm7vT2xK9pLr4sWz",
"traffic_limit_gb": 25,
"traffic_used_gb": 6.412,
"status": "active",
"created_at": "2026-09-14T08:05:22Z"
},
{
"id": "su_8d1f4n6p",
"name": "qa-team",
"username": "sub_p8w2n5tf",
"password": "Hx4bN9cR2vLq7mKs",
"traffic_limit_gb": null,
"traffic_used_gb": 1.207,
"status": "disabled",
"created_at": "2026-09-20T13:47:09Z"
}
]
}Создание субпользователя
POST /sub-users
Параметры
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
name | string, в теле запроса | Да | Название длиной от 1 до 64 символов, уникальное в пределах аккаунта |
traffic_limit_gb | number или null, в теле запроса | Нет | Лимит трафика в ГБ, больше 0. Чтобы не ограничивать трафик, не передавайте параметр или передайте null |
Пример запроса
curl -X POST https://api.proxonym.com/v1/sub-users \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "eu-crawler", "traffic_limit_gb": 10}'Пример ответа
Код ответа 201, со сгенерированными именем пользователя и паролем:
{
"id": "su_6v2c8r1t",
"name": "eu-crawler",
"username": "sub_t6r1y8bw",
"password": "Lp3sV8kQ1zXn6wRd",
"traffic_limit_gb": 10,
"traffic_used_gb": 0,
"status": "active",
"created_at": "2026-10-01T09:30:00Z"
}Если название уже занято, возвращается 409 с already_exists. Новые учётные данные сразу работают на шлюзе с обычными параметрами имени пользователя:
curl -x http://gw.proxonym.com:8000 \
-U "sub_t6r1y8bw-country-de:Lp3sV8kQ1zXn6wRd" \
https://api.ipify.orgИзменение субпользователя
PATCH /sub-users/{id}
Передавайте только те поля, которые хотите изменить.
Параметры
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
id | string, в пути | Да | ID субпользователя |
name | string, в теле запроса | Нет | Новое название, от 1 до 64 символов |
traffic_limit_gb | number или null, в теле запроса | Нет | Новый лимит в ГБ или null, чтобы снять ограничение |
status | string, в теле запроса | Нет | active или disabled |
reset_password | boolean, в теле запроса | Нет | true генерирует новый пароль. Старый сразу перестаёт работать |
Пример запроса
Повысить лимит и сбросить пароль:
curl -X PATCH https://api.proxonym.com/v1/sub-users/su_3k9x2m7q \
-H "Authorization: Bearer $PROXONYM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"traffic_limit_gb": 40, "reset_password": true}'Пример ответа
{
"id": "su_3k9x2m7q",
"name": "price-monitor",
"username": "sub_k3v9q2xd",
"password": "Wd5nX8qT3vKz6pRm",
"traffic_limit_gb": 40,
"traffic_used_gb": 6.412,
"status": "active",
"created_at": "2026-09-14T08:05:22Z"
}Удаление субпользователя
DELETE /sub-users/{id}
Удаляет субпользователя, и его учётные данные сразу перестают работать. Уже израсходованный им трафик остаётся в статистике расхода. Чтобы вместо удаления приостановить субпользователя, задайте полю status значение disabled.
Параметры
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
id | string, в пути | Да | ID субпользователя |
Пример запроса
curl -X DELETE https://api.proxonym.com/v1/sub-users/su_8d1f4n6p \
-H "Authorization: Bearer $PROXONYM_API_KEY"Пример ответа
{
"id": "su_8d1f4n6p",
"deleted": true
}Для неизвестного ID возвращается 404 с not_found.
SERP API#
Google SERP API возвращает результаты поиска Google в виде структурированного JSON для любой страны или города, для десктопа или мобильных устройств. Каждый вызов возвращает одну страницу выдачи и учитывается как один запрос по вашему тарифу.
Поиск
GET https://serp.proxonym.com/v1/search
Передавайте ключ SERP API из личного кабинета в заголовке X-API-Key. Ошибки имеют тот же формат, что и в API аккаунта: при отсутствующем или недействительном ключе возвращается 401 с invalid_api_key. Без активного тарифа SERP API возвращает 403 с product_not_active, а когда запросы тарифа израсходованы, — 403 с quota_exceeded.
Параметры
| Название | Тип | Обязательный | Описание |
|---|---|---|---|
q | string | Да | Поисковый запрос в URL-кодировке |
gl | string | Нет | Страна выдачи: код ISO 3166-1 alpha-2 в нижнем регистре. По умолчанию us |
hl | string | Нет | Код языка интерфейса, например en или de. По умолчанию en |
location | string | Нет | Местоположение с точностью до города в формате City,Region, например Chicago,Illinois. Указывайте место внутри страны, заданной в gl |
device | string | Нет | desktop (по умолчанию) или mobile |
page | integer | Нет | Страница выдачи, начиная с 1 (по умолчанию). Каждая страница — отдельный запрос |
Пример запроса
curl -G https://serp.proxonym.com/v1/search \
-H "X-API-Key: $PROXONYM_SERP_KEY" \
--data-urlencode "q=running shoes" \
-d gl=us \
-d hl=en \
--data-urlencode "location=Chicago,Illinois" \
-d device=desktop \
-d page=1Тот же запрос на Python:
import os
import requests
params = {
"q": "running shoes",
"gl": "us",
"hl": "en",
"location": "Chicago,Illinois",
"device": "desktop",
"page": 1,
}
r = requests.get(
"https://serp.proxonym.com/v1/search",
headers={"X-API-Key": os.environ["PROXONYM_SERP_KEY"]},
params=params,
timeout=60,
)
r.raise_for_status()
for result in r.json()["organic_results"]:
print(result["position"], result["title"], result["link"])Пример ответа
Ответ сокращён:
{
"search_parameters": {
"q": "running shoes",
"gl": "us",
"hl": "en",
"location": "Chicago,Illinois",
"device": "desktop",
"page": 1
},
"organic_results": [
{
"position": 1,
"title": "Running Shoes for Men and Women | Stride Supply",
"link": "https://www.stridesupply.example/running-shoes",
"snippet": "Shop road and trail running shoes in every size. Compare cushioning, drop and weight across 40 models."
},
{
"position": 2,
"title": "How to Choose Running Shoes: A Buyer's Guide",
"link": "https://www.runnersdesk.example/guides/choosing-running-shoes",
"snippet": "Gait, arch type and weekly mileage matter more than brand. Here is how to narrow the field."
},
{
"position": 3,
"title": "Running Shoes in Chicago, IL | Lakeshore Run Co.",
"link": "https://www.lakeshorerun.example/",
"snippet": "Gait analysis and fittings at our Lincoln Park store, open 7 days a week."
}
],
"ads": [
{
"position": 1,
"title": "Running Shoes Sale | Up to 40% Off",
"link": "https://www.shoeoutlet.example/running",
"snippet": "Last season's models in stock. Ships in 1 business day."
}
],
"people_also_ask": [
{
"question": "How often should you replace running shoes?",
"snippet": "Many runners replace their shoes every 300 to 500 miles.",
"link": "https://www.runnersdesk.example/guides/shoe-lifespan"
}
],
"related_searches": [
{ "query": "running shoes near me" },
{ "query": "trail running shoes" },
{ "query": "running shoes for flat feet" }
],
"local_results": [
{
"position": 1,
"title": "Lakeshore Run Co.",
"address": "2312 N Lincoln Ave, Chicago, IL",
"phone": "(312) 555-0142"
},
{
"position": 2,
"title": "Windy City Running",
"address": "845 W Randolph St, Chicago, IL",
"phone": "(312) 555-0187"
}
]
}Поля ответа
| Поле | Тип | Описание |
|---|---|---|
search_parameters | object | Параметры поиска с подставленными значениями по умолчанию |
organic_results[] | array | Органические результаты в порядке следования на странице |
organic_results[].position | integer | Позиция на странице, начиная с 1 |
organic_results[].title | string | Заголовок результата |
organic_results[].link | string | URL результата |
organic_results[].snippet | string | Текст под заголовком |
ads[] | array | Платные результаты с полями position, title, link и snippet |
people_also_ask[] | array | Вопросы из блока «People also ask» с полями question, snippet и link |
related_searches[] | array | Связанные запросы, у каждого — поле query |
local_results[] | array | Результаты локального блока с полями position, title, address и phone |
Блоки, которых нет на странице, возвращаются пустыми массивами. Чтобы отслеживать позиции в динамике, см. сценарий отслеживания позиций в выдаче и наше руководство по парсингу результатов поиска Google.