НовинкаБезлимитные резидентные прокси: трафик без учёта объёма по фиксированной цене. От $33,25/день

Справочник API

Справочник API Proxonym

Управляйте балансами, расходом, списками прокси, белым списком IP и субпользователями через JSON REST API, а структурированную выдачу Google получайте через SERP API.

  • Базовый URLhttps://api.proxonym.com/v1
  • АутентификацияAuthorization: Bearer API_KEY
  • ФорматJSON
  • Лимит запросов60 / min

Обзор#

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}Удалить субпользователя
GEThttps://serp.proxonym.com/v1/searchВыдача Google в виде структурированного JSON

Первый вызов

Создайте API-ключ в личном кабинете, экспортируйте его в переменную окружения, а затем запросите данные аккаунта:

Shell
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:

Shell
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-ключи — это не учётные данные прокси. Для подключения к прокси используются ваши имя пользователя и пароль прокси; см. аутентификацию прокси.

Ротация ключей

  1. Создайте новый ключ в личном кабинете.
  2. Разверните его во всех сервисах, которые вызывают API.
  3. Убедитесь, что вызовы с новым ключом проходят успешно, затем отзовите старый.

Меняйте ключи по расписанию и немедленно отзывайте ключ, если он мог утечь. Запросы с отозванным ключом завершаются ошибкой 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, и повторите запрос. Чтобы не превышать лимит:

  • Кэшируйте редко меняющиеся данные, например списки прокси и белый список.
  • Запрашивайте расход раз в несколько минут, а не каждые несколько секунд. Минимальная детализация — один час.
  • Растягивайте пакетные операции, например создание большого числа субпользователей, на несколько минут.
Python
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:

JSON
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is missing, malformed or revoked."
  }
}

Стройте логику обработки на code и никогда — на message: формулировки сообщений могут меняться, а коды остаются стабильными.

СтатусКодЗначениеЧто делать
400invalid_requestЗапрос сформирован неверно: невалидный JSON, не указан обязательный параметр или значение имеет неверный типИсправьте запрос. Повтор не поможет
401invalid_api_keyAPI-ключ отсутствует, сформирован неверно или отозванПроверьте заголовок и ключ
403product_not_active, quota_exceededКлюч действителен, но у продукта нет активного тарифа или в тарифе SERP закончились запросыКупите или продлите тариф
404not_foundПуть, продукт, ID субпользователя или IP в белом списке не существуетПроверьте путь и ID
409already_existsIP уже есть в белом списке, или это название уже занято другим субпользователемИспользуйте существующий ресурс или выберите другое значение
422validation_failed, whitelist_fullЗначение имеет правильный формат, но не принимается (например, недопустимый IP, неизвестный продукт или слишком длинный диапазон дат), либо заняты все слоты белого спискаИсправьте значение или сначала удалите IP из белого списка
429rate_limitedБолее 60 запросов за минутуПодождите указанное в Retry-After число секунд и повторите запрос
500internal_errorНепредвиденная ошибка на нашей сторонеПовторите запрос с экспоненциальной задержкой

Повторять без изменений стоит только запросы, получившие 429 или 500. Если ошибка 500 не исчезает, запишите эндпоинт, время запроса и полное тело ошибки: на тарифе с выделенными прокси дата-центров отправьте их нашей команде в тикете.

Аккаунт#

Получайте данные аккаунта, балансы ГБ и активные тарифы.

Получение данных аккаунта

GET /account

Возвращает аккаунт, его балансы ГБ и все активные тарифы. Истёкшие тарифы не включаются.

Параметры

Нет.

Пример запроса

Shell
curl https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Пример ответа

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

Поля ответа

ПолеТипОписание
idstringID аккаунта
emailstringАдрес электронной почты аккаунта
created_atstringВремя создания аккаунта
credit_usdnumberБаланс аккаунта в долларах США, доступный для покупки тарифов. Пополнения и бонусные средства зачисляются на него
balancesobjectБалансы ГБ, где ключ — продукт: residential (общий с мобильными прокси) и datacenter (месячный объём трафика). Продукты без баланса не включаются
balances.{product}.gb_remainingnumber или nullОстаток ГБ. null на уровне дата-центров «Без ограничений»
balances.{product}.expires_atstring или 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, udpinteger, string, booleanБезлимитные резидентные прокси: уровень скорости, сервер шлюза и признак активной опции UDP
plans[].ipsintegerISP, дата-центры и выделенные прокси: количество IP
plans[].bandwidth_gbinteger или nullДата-центры: месячный объём трафика в ГБ, null на уровне «Без ограничений»
plans[].requests_limit, requests_usedintegerSERP API: число запросов, включённых в тариф, и число уже использованных запросов

Мобильный трафик списывается с резидентного баланса, поэтому отдельного баланса mobile нет. Резидентные пакеты ГБ отображаются в balances, а не в plans. Тарифы никогда не продлеваются автоматически: сравнивайте expires_at с текущим временем, чтобы решить, когда продлевать.

Пример: предупреждение о низком балансе

Python
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

Возвращает расход одного продукта за период: итог и временной ряд.

Параметры

НазваниеТипОбязательныйОписание
productstring, в строке запросаДаresidential, mobile, unlimited, isp, datacenter, dedicated или serp
fromstring, в строке запросаНетНачало периода включительно: дата или временная метка ISO 8601 в UTC. По умолчанию — за 7 дней до to
tostring, в строке запросаНетКонец периода (не включительно). По умолчанию — текущий момент
granularitystring, в строке запросаНетday (по умолчанию) или hour. Интервалы выравниваются по UTC

Период может охватывать до 366 дней при детализации day и до 31 дня при hour. Более длинный период или from позже to возвращает 422 с validation_failed. Расход мобильных прокси показывается отдельно, но списывается с резидентного баланса.

Пример запроса

Shell
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

Пример ответа

JSON
{
  "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, granularitystringЗначения, использованные в запросе
from, tostringИтоговый период в виде временных меток UTC
total.traffic_gbnumberТрафик за период в ГБ. Только для прокси-продуктов
total.requestsintegerЗапросы SERP API за период. Только для serp
series[]arrayПо одной точке на интервал в хронологическом порядке. Для интервалов без расхода возвращается 0
series[].timestampstringНачало интервала
series[].traffic_gb или series[].requestsnumber или integerРасход за интервал в тех же единицах, что и total

Для serp итоги и точки считаются в запросах, а не в ГБ. Почасовой запрос, например ?product=serp&from=2026-09-30T00:00:00Z&to=2026-09-30T03:00:00Z&granularity=hour, возвращает:

JSON
{
  "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 или обычным текстом, по одному прокси в строке.

Параметры

НазваниеТипОбязательныйОписание
productstring, в путиДаdatacenter, isp или dedicated
formatstring, в строке запросаНетjson (по умолчанию) или txt
countrystring, в строке запросаНетВернуть только прокси в этой стране: код ISO 3166-1 alpha-2 в нижнем регистре, например us

Пример запроса

Shell
curl https://api.proxonym.com/v1/proxies/isp \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Пример ответа

Сокращено до трёх записей; count — полное количество.

JSON
{
  "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-прокси и выделенных прокси.

Shell
curl -G https://api.proxonym.com/v1/proxies/datacenter \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -d format=txt \
  -d country=us
Текст
198.51.100.23:3129
198.51.100.87:3129
198.51.100.142:3129

Поля прокси

ПолеПродуктыОписание
ipВсеIP-адрес прокси
portISP, выделенныеПорт для HTTP и SOCKS5
http_port, socks5_portДата-центрПорт HTTP 3129 и порт SOCKS5 1081
username, passwordISP, выделенныеУчётные данные этого прокси
countryВсеСтрана IP: код ISO 3166-1 alpha-2 в нижнем регистре
locationISPГород или пул провайдера, например New York или Comcast pool
expires_atISP, выделенныеОкончание срока действия этого IP

Запись для дата-центров в JSON выглядит так: {"ip": "198.51.100.23", "http_port": 3129, "socks5_port": 1081, "country": "us"}. Если у продукта нет активного тарифа, API возвращает 403 с product_not_active. Для продукта без списка, например residential, возвращается 404:

JSON
{
  "error": {
    "code": "not_found",
    "message": "No proxy list for product residential. Lists exist for datacenter, isp and dedicated."
  }
}

Белый список#

Белый список позволяет машинам подключаться к вашим общим прокси дата-центров без учётных данных. Каждый тариф на общие прокси дата-центров включает 3 слота, а записи действуют для всех ваших IP дата-центров. Подробнее — в разделе документации «Белый список IP».

Получение IP из белого списка

GET /whitelist

Параметры

Нет.

Пример запроса

Shell
curl https://api.proxonym.com/v1/whitelist \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Пример ответа

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

Параметры

НазваниеТипОбязательныйОписание
ipstring, в теле запросаДаПубличный IP-адрес машины, которая будет подключаться, например 192.0.2.44

Пример запроса

Shell
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:

JSON
{
  "ip": "192.0.2.44",
  "created_at": "2026-10-01T09:30:00Z"
}

Для IP, который уже есть в списке, возвращается 409 с already_exists, а для недопустимого адреса — 422 с validation_failed. Если заняты все слоты, API возвращает 422:

JSON
{
  "error": {
    "code": "whitelist_full",
    "message": "All 3 whitelist slots are in use. Remove an IP before adding another."
  }
}

Удаление IP

DELETE /whitelist/{ip}

Параметры

НазваниеТипОбязательныйОписание
ipstring, в путиДаIP из белого списка, который нужно удалить

Пример запроса

Shell
curl -X DELETE https://api.proxonym.com/v1/whitelist/192.0.2.10 \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Пример ответа

JSON
{
  "ip": "192.0.2.10",
  "deleted": true
}

После этого запросы с этого IP без учётных данных завершаются ошибкой 407. Для IP, которого нет в списке, возвращается 404 с not_found.

Субпользователи#

Субпользователи — это дополнительные учётные данные прокси в вашем аккаунте, у каждого из которых может быть свой лимит трафика. Их трафик списывается с баланса аккаунта. Подробнее — в разделе документации «Субпользователи».

Объект субпользователя

JSON
{
  "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"
}
ПолеТипОписание
idstringID субпользователя, используется в путях API
namestringВаше название для субпользователя, уникальное в пределах аккаунта
usernamestringИмя пользователя прокси, генерируется автоматически. Принимает те же параметры, что и ваше основное имя пользователя, например sub_k3v9q2xd-country-us-session-a7k2
passwordstringПароль прокси, генерируется автоматически
traffic_limit_gbnumber или nullМаксимальный трафик в ГБ. null — лимита нет, трафик ограничен только балансом аккаунта
traffic_used_gbnumberИзрасходованный трафик в ГБ
statusstringactive или disabled. Отключённым субпользователям прокси отвечает 407
created_atstringВремя создания субпользователя

Когда traffic_used_gb достигает traffic_limit_gb, запросы субпользователя завершаются ошибкой 402, пока вы не повысите лимит.

Получение списка субпользователей

GET /sub-users

Параметры

Нет.

Пример запроса

Shell
curl https://api.proxonym.com/v1/sub-users \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Пример ответа

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

Параметры

НазваниеТипОбязательныйОписание
namestring, в теле запросаДаНазвание длиной от 1 до 64 символов, уникальное в пределах аккаунта
traffic_limit_gbnumber или null, в теле запросаНетЛимит трафика в ГБ, больше 0. Чтобы не ограничивать трафик, не передавайте параметр или передайте null

Пример запроса

Shell
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, со сгенерированными именем пользователя и паролем:

JSON
{
  "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. Новые учётные данные сразу работают на шлюзе с обычными параметрами имени пользователя:

Shell
curl -x http://gw.proxonym.com:8000 \
  -U "sub_t6r1y8bw-country-de:Lp3sV8kQ1zXn6wRd" \
  https://api.ipify.org

Изменение субпользователя

PATCH /sub-users/{id}

Передавайте только те поля, которые хотите изменить.

Параметры

НазваниеТипОбязательныйОписание
idstring, в путиДаID субпользователя
namestring, в теле запросаНетНовое название, от 1 до 64 символов
traffic_limit_gbnumber или null, в теле запросаНетНовый лимит в ГБ или null, чтобы снять ограничение
statusstring, в теле запросаНетactive или disabled
reset_passwordboolean, в теле запросаНетtrue генерирует новый пароль. Старый сразу перестаёт работать

Пример запроса

Повысить лимит и сбросить пароль:

Shell
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}'

Пример ответа

JSON
{
  "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.

Параметры

НазваниеТипОбязательныйОписание
idstring, в путиДаID субпользователя

Пример запроса

Shell
curl -X DELETE https://api.proxonym.com/v1/sub-users/su_8d1f4n6p \
  -H "Authorization: Bearer $PROXONYM_API_KEY"

Пример ответа

JSON
{
  "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.

Параметры

НазваниеТипОбязательныйОписание
qstringДаПоисковый запрос в URL-кодировке
glstringНетСтрана выдачи: код ISO 3166-1 alpha-2 в нижнем регистре. По умолчанию us
hlstringНетКод языка интерфейса, например en или de. По умолчанию en
locationstringНетМестоположение с точностью до города в формате City,Region, например Chicago,Illinois. Указывайте место внутри страны, заданной в gl
devicestringНетdesktop (по умолчанию) или mobile
pageintegerНетСтраница выдачи, начиная с 1 (по умолчанию). Каждая страница — отдельный запрос

Пример запроса

Shell
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:

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"])

Пример ответа

Ответ сокращён:

JSON
{
  "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_parametersobjectПараметры поиска с подставленными значениями по умолчанию
organic_results[]arrayОрганические результаты в порядке следования на странице
organic_results[].positionintegerПозиция на странице, начиная с 1
organic_results[].titlestringЗаголовок результата
organic_results[].linkstringURL результата
organic_results[].snippetstringТекст под заголовком
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.