---
title: "Справочник API прокси: расход, списки прокси и SERP"
description: "REST API Proxonym: API-ключи, лимиты запросов, ошибки и эндпоинты для аккаунта, расхода трафика, списков прокси, белого списка IP, субпользователей и SERP API."
url: https://proxonym.com/ru/docs/api
updated: 2026-10-02T03:03:46+00:00
---

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

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

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

### Содержание

Кратко об API

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

Эндпоинты

- [`GET` /account](https://proxonym.com/ru/docs/api#account)
- [`GET` /usage](https://proxonym.com/ru/docs/api#usage)
- [`GET` /proxies/{product}](https://proxonym.com/ru/docs/api#proxy-lists)
- [`GET POST DEL` /whitelist](https://proxonym.com/ru/docs/api#whitelist)
- [`GET POST PATCH DEL` /sub-users](https://proxonym.com/ru/docs/api#sub-users)
- [`GET` serp…/v1/search](https://proxonym.com/ru/docs/api#serp-api)

**Не получается?** В справочном центре разобраны вопросы оплаты, ошибок и работы с аккаунтом.

[Справочный центр](https://proxonym.com/ru/help) [Проверить прокси](https://proxonym.com/ru/proxy-checker)

## Обзор

API Proxonym позволяет управлять аккаунтом из кода: получать балансы и тарифы, выгружать данные о расходе, скачивать списки прокси, редактировать белый список IP и управлять субпользователями. Google SERP API работает на отдельном хосте и возвращает структурированные результаты поиска в формате JSON.

### Базовый URL

**Текст**

```text
https://api.proxonym.com/v1
```

Пути в этом справочнике указаны относительно базового URL. Все запросы выполняются по HTTPS. У SERP API собственный базовый URL — `https://serp.proxonym.com/v1`.

### Описание в формате OpenAPI

API аккаунта также описан в формате OpenAPI 3.1 по адресу [/docs/api/openapi.json](https://proxonym.com/docs/api/openapi.json) — это описание подходит для генераторов клиентов, инструментов для работы с API и ИИ-агентов.

### Версионирование

Мажорная версия входит в путь. Изменения, нарушающие совместимость, выходят только в новой версии. В рамках `v1` могут появляться новые эндпоинты, необязательные параметры и поля ответа, поэтому пишите клиенты так, чтобы они игнорировали незнакомые поля.

### Соглашения

- **Формат:** ответы приходят в JSON в кодировке UTF-8 с заголовком `Content-Type: application/json`, кроме списков прокси, запрошенных с `format=txt`. Тело запроса отправляйте в JSON с заголовком `Content-Type: application/json`.
- **Коды ответа:** `200` при успехе и `201` при создании ресурса. Ошибки описаны в разделе «[Ошибки](https://proxonym.com/ru/docs/api#errors)».
- **Временные метки:** 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`](https://proxonym.com/ru/docs/api#account-get) | Аккаунт, балансы ГБ и активные тарифы |
| `GET` | [`/usage`](https://proxonym.com/ru/docs/api#usage-get) | Расход одного продукта за период |
| `GET` | [`/proxies/{product}`](https://proxonym.com/ru/docs/api#proxy-lists-get) | Список прокси дата-центров, ISP-прокси или выделенных прокси |
| `GET` | [`/whitelist`](https://proxonym.com/ru/docs/api#whitelist-list) | Получить IP из белого списка |
| `POST` | [`/whitelist`](https://proxonym.com/ru/docs/api#whitelist-add) | Добавить IP в белый список |
| `DELETE` | [`/whitelist/{ip}`](https://proxonym.com/ru/docs/api#whitelist-remove) | Удалить IP из белого списка |
| `GET` | [`/sub-users`](https://proxonym.com/ru/docs/api#sub-users-list) | Получить список субпользователей |
| `POST` | [`/sub-users`](https://proxonym.com/ru/docs/api#sub-users-create) | Создать субпользователя |
| `PATCH` | [`/sub-users/{id}`](https://proxonym.com/ru/docs/api#sub-users-update) | Изменить субпользователя |
| `DELETE` | [`/sub-users/{id}`](https://proxonym.com/ru/docs/api#sub-users-delete) | Удалить субпользователя |
| `GET` | [`https://serp.proxonym.com/v1/search`](https://proxonym.com/ru/docs/api#serp-api-search) | Выдача Google в виде структурированного JSON |

### Первый вызов

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

**Shell**

```bash
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`:

**Текст**

```text
Authorization: Bearer <API_KEY>
```

Ключи создаются и отзываются в личном кабинете. Ключ действует на весь аккаунт: с ним можно читать расход, скачивать учётные данные прокси и управлять субпользователями. Запрос с отсутствующим, неверно сформированным или отозванным ключом завершается ошибкой `401`:

**Shell**

```bash
curl -i https://api.proxonym.com/v1/account \
  -H "Authorization: Bearer wrong_key"
```

**Текст**

```text
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-ключи — это не учётные данные прокси. Для подключения к прокси используются ваши имя пользователя и пароль прокси; см. [аутентификацию прокси](https://proxonym.com/ru/docs#authentication).

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

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

Меняйте ключи по расписанию и немедленно отзывайте ключ, если он мог утечь. Запросы с отозванным ключом завершаются ошибкой `401`.

### Ключ SERP API

SERP API принимает ключ в заголовке `X-API-Key`, а не `Authorization`. См. раздел «[SERP API](https://proxonym.com/ru/docs/api#serp-api)».

## Лимиты запросов

API аккаунта принимает 60 запросов в минуту. Каждый ответ сообщает, сколько запросов у вас осталось:

| Заголовок | Описание |
| --- | --- |
| `X-RateLimit-Limit` | Разрешённое число запросов в минуту: `60` |
| `X-RateLimit-Remaining` | Сколько запросов осталось в текущем окне |
| `Retry-After` | Только в ответах `429`: через сколько секунд можно отправить следующий запрос |

При превышении лимита API отвечает `429`:

**Текст**

```text
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](https://proxonym.com/ru/docs/api#serp-api)».

### Обработка 429

Подождите столько секунд, сколько указано в `Retry-After`, и повторите запрос. Чтобы не превышать лимит:

- Кэшируйте редко меняющиеся данные, например списки прокси и белый список.
- Запрашивайте расход раз в несколько минут, а не каждые несколько секунд. Минимальная детализация — один час.
- Растягивайте пакетные операции, например создание большого числа субпользователей, на несколько минут.

**Python**

```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**

```json
{
  "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`

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

#### Параметры

Нет.

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

**Shell**

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

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

**JSON**

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

#### Поля ответа

| Поле | Тип | Описание |
| --- | --- | --- |
| `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` с текущим временем, чтобы решить, когда продлевать.

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

**Python**

```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`

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

#### Параметры

| Название | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| `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`. Расход мобильных прокси показывается отдельно, но списывается с резидентного баланса.

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

**Shell**

```bash
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**

```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`, `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`, возвращает:

**JSON**

```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 }
  ]
}
```

## Списки прокси

Скачивайте прокси, закреплённые за вашими статическими тарифами. У резидентных, мобильных и безлимитных резидентных прокси списка нет: к ним подключаются через шлюз, описанный в разделе «[Эндпоинты и порты](https://proxonym.com/ru/docs#endpoints-and-ports)».

### Получение списка прокси

`GET /proxies/{product}`

Возвращает все прокси ваших активных тарифов по одному продукту — в JSON или обычным текстом, по одному прокси в строке.

#### Параметры

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

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

**Shell**

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

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

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

**JSON**

```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**

```bash
curl -G https://api.proxonym.com/v1/proxies/datacenter \
  -H "Authorization: Bearer $PROXONYM_API_KEY" \
  -d format=txt \
  -d country=us
```

**Текст**

```text
198.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`:

**JSON**

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

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

Белый список позволяет машинам подключаться к вашим общим прокси дата-центров без учётных данных. Каждый тариф на общие прокси дата-центров включает 3 слота, а записи действуют для всех ваших IP дата-центров. Подробнее — в разделе документации «[Белый список IP](https://proxonym.com/ru/docs#authentication-ip-whitelist)».

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

`GET /whitelist`

#### Параметры

Нет.

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

**Shell**

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

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

**JSON**

```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`

#### Параметры

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

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

**Shell**

```bash
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**

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

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

**JSON**

```json
{
  "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 из белого списка, который нужно удалить |

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

**Shell**

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

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

**JSON**

```json
{
  "ip": "192.0.2.10",
  "deleted": true
}
```

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

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

Субпользователи — это дополнительные учётные данные прокси в вашем аккаунте, у каждого из которых может быть свой лимит трафика. Их трафик списывается с баланса аккаунта. Подробнее — в разделе документации «[Субпользователи](https://proxonym.com/ru/docs#authentication-sub-users)».

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

**JSON**

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `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`

#### Параметры

Нет.

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

**Shell**

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

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

**JSON**

```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`

#### Параметры

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

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

**Shell**

```bash
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**

```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**

```bash
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` генерирует новый пароль. Старый сразу перестаёт работать |

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

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

**Shell**

```bash
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**

```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`.

#### Параметры

| Название | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| `id` | string, в пути | Да | ID субпользователя |

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

**Shell**

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

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

**JSON**

```json
{
  "id": "su_8d1f4n6p",
  "deleted": true
}
```

Для неизвестного ID возвращается `404` с `not_found`.

## SERP API

[Google SERP API](https://proxonym.com/ru/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` (по умолчанию). Каждая страница — отдельный запрос |

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

**Shell**

```bash
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**

```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**

```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_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` |

Блоки, которых нет на странице, возвращаются пустыми массивами. Чтобы отслеживать позиции в динамике, см. [сценарий отслеживания позиций в выдаче](https://proxonym.com/ru/use-cases/serp-tracking) и наше руководство по [парсингу результатов поиска Google](https://proxonym.com/ru/blog/scrape-google-search-results).

- [Документация](https://proxonym.com/ru/docs): Шлюз, сессии, таргетинг, ошибки
- [Интеграции](https://proxonym.com/ru/integrations): Puppeteer, Playwright, Scrapy и другие
