1 Перед началом

API живёт на https://geekproxy.io, отдельного хоста нет. Справочник на geekproxy.io/api/docs рисует спецификацию OpenAPI 3.0 (GeekProxy API 1.0.0), сырой файл лежит на /api/swagger. Все запросы и ответы в JSON. SDK нет, и он не нужен.

• Авторизация по Bearer-токену из POST /api/login. Живёт 24 часа, и у аккаунта активен только один токен за раз
• Без токена работает только POST /api/login
• Оплата с баланса проходит синхронно. Внешние способы оплаты возвращают платёжную ссылку, которую должен открыть человек, поэтому скрипты без оператора сначала пополняют баланс

Что понадобится

• Аккаунт GeekProxy: та же почта и пароль, что и для кабинета
• Баланс на аккаунте, если собираетесь покупать или продлевать из скрипта
• curl или Python 3 с requests

2 Вход и получение токена

Отправьте почту и пароль от кабинета в POST /api/login. В ответе access_token, token_type Bearer и expires_in 86400. Токен кладётся в заголовок Authorization каждого следующего вызова. Эндпоинт входа ограничен по частоте, так что не дёргайте его на каждый запрос: вошли один раз, закешировали токен, вошли заново по 401.

curl -s -X POST https://geekproxy.io/api/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "[email protected]", "password": "your-password"}'
# {"access_token": "oat_...", "token_type": "Bearer", "expires_in": 86400}

curl -s https://geekproxy.io/api/me -H "Authorization: Bearer $TOKEN"

Одно правило ловит людей чаще, чем кажется: удачный вход отзывает все прежние токены этого пользователя. Одна активная сессия. Если cron и ваш ноутбук входят оба, второй молча убивает первого. Заведите каждому окружению свой аккаунт или делите между ними один закешированный токен.

import requests

BASE = "https://geekproxy.io"

r = requests.post(f"{BASE}/api/login",
                  json={"email": "[email protected]", "password": "your-password"},
                  timeout=30)
r.raise_for_status()
TOKEN = r.json()["access_token"]        # живёт 86400 с, один активный токен на аккаунт
H = {"Authorization": f"Bearer {TOKEN}"}

me = requests.get(f"{BASE}/api/me", headers=H, timeout=30).json()
print(me["balance"], me["is_verified"])

GET /api/me возвращает профиль с balance, is_verified и locale. POST /api/logout завершает сессию. Данные за экраном кабинета ниже API отдаёт тем же JSON.

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

У каждого семейства продуктов свой эндпоинт списка, потому что строка прокси собирается по-разному. Сначала POST /api/subscriptions/list отдаёт id подписок (per_page не больше 100).

Планы с оплатой за IP

Shared, dedicated и flawless целиком описаны ответом POST /api/subscriptions/details. В блоке connection лежат login, password, массив ips и объект ports, например {"http/https": 8080, "socks5": 1080}. Строку login:password@ip:port собираете сами.

Residential Turbo

POST /api/turbo/proxy-list зашивает таргетинг в логин. Хост и порты одни на все подписки Turbo. Таргетинг: country (ISO2), city и pool 1 или 2. Сессия: session_id до 64 символов и session_time от 1 до 1440 минут. Дальше mode_fast, mode_udp (только SOCKS5, на практике несовместим с mode_fast), protocol http или socks5, quantity от 1 до 10000. Поле format задаёт форму: default это host:port:login:password, secondary это login:password@host:port, а http_url и socks5_url дают полные URL. Turbo это только HTTP и SOCKS5, HTTPS-порта у него нет.

r = requests.post(f"{BASE}/api/turbo/proxy-list", headers=H, json={
    "subscription_id": 219,
    "country": "us",
    "city": "New York",
    "pool": 1,
    "mode_fast": True,
    "session_id": "ab12cd34ef",  # sticky: один выход на session_time минут
    "session_time": 10,
    "protocol": "http",
    "format": "default",         # host:port:login:password
    "quantity": 3,
}, timeout=30)
print(r.text)
# по строке на прокси, например
# rst.geekproxy.net:8989:acme1234-package-standard-country-us-city-newyork-pool-1-mode-fast-session-ab12cd34ef-time-10:s3cret

Residential Flex и старое резидентское семейство

POST /api/flex/proxy-list устроен так же, но точка входа региональная и своя у подписки (в примере хост usf.geekproxy.net:8888). Суффиксы логина: -cont-, -cc-, -region-, -city-, -asn-, -os-windows или -os-android и -strict-false. Без полей сессии идёт ротация; session_time от 1 до 120 минут (по умолчанию 5) делает её статической, причём сессия держится только вместе хотя бы с одной опцией таргетинга. format это число от 1 до 6, где 4 даёт полный URL scheme://login:password@host:port и для SOCKS5 подставляет socks5h, чтобы DNS резолвился на прокси. Резидентское и мобильное семейство ходит в POST /api/resident-proxy/proxy-list с type rotating или sticky, session_ttl до 1440 минут и свободным шаблоном format из {login}, {password}, {hostname} и {port}. Списки ISP в разделе 5.

4 Покупка, продление, докупка трафика

Начните с каталога. POST /api/available/packets возвращает планы в продаже, сгруппированные по типу; документация просит сопоставлять по num, а не по названию, и ISP-планов в этом списке нет. GET /api/available/payments отдаёт способы оплаты как id плюс paymentName, и среди них есть оплата с баланса, нужная для запусков без оператора.

Потом покупка. POST /api/subscriptions/buy принимает packet_id, price_id, payment_type_id, необязательные country_id или worldpart_id, промокод promo и колбэки success_url и fail_url. При оплате с баланса подписка выдаётся синхронно, и колбэк срабатывает сразу. При внешнем способе возвращается {"status": "processing", "paymentUrl": "...", "billing_id": 297}, и кто-то должен открыть эту ссылку.

# продление с баланса; BALANCE_ID берём из GET /api/available/payments
curl -s -X POST https://geekproxy.io/api/subscriptions/renew \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: renew-179-2026-11' \
  -d '{"subscription_id": 179, "price_id": 1, "payment_type_id": '"$BALANCE_ID"'}'

# докупить 10 ГБ трафиковому плану; срок не меняется
curl -s -X POST https://geekproxy.io/api/subscriptions/topup \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: topup-179-0001' \
  -d '{"subscription_id": 179, "gb": 10, "payment_type_id": '"$BALANCE_ID"'}'

Три правила из справочника. POST /api/subscriptions/renew продлевает нерезидентские планы только пока они активны (status_id = 1), так что ставьте задачу до истечения, а не после. POST /api/subscriptions/topup берёт целые гигабайты от 1 до 500 по цене гигабайта в плане и отвечает 400 на планах за IP. И каждая покупка, продление, докупка и пополнение принимают заголовок Idempotency-Key до 128 символов. Один и тот же ключ возвращает тот же биллинг, поэтому повторённый запрос не спишет деньги дважды. Ставьте его всегда.

5 ISP-планы и белые списки IP

ISP-адреса покупаются в четыре шага, все под тегом ISP. POST /api/isp/packets перечисляет пакеты, isp_type 1 для Basic и 2 для Premium. POST /api/isp/locations отдаёт страны и города. POST /api/isp/prices возвращает price_id под ваше количество и срок. Наконец POST /api/subscriptions/buy-isp списывает деньги с баланса. Выдача асинхронная, поэтому адреса забирайте потом через POST /api/isp/proxy-list или POST /api/isp/refresh-instances. Список приходит как один общий port плюс массив access с ip, login и password на каждый адрес. Город, где свободных адресов меньше трёх, отбивается с 400, а ещё в документации описан исход "refunded": true, так что читайте тело ответа, а не один код.

Белые списки и опции планов за IP

Для shared, dedicated и flawless POST /api/proxy/update-options меняет одним вызовом любое сочетание allowed_ip, auth_enabled, socks5_udp_enabled, socks5_streaming_enabled и http_streaming_enabled. Документированное тело: {"subscription_id": 179, "allowed_ip": "1.2.3.4", "auth_enabled": true, ...}. У резидентского и мобильного семейства есть POST /api/resident-proxy/allowed-ips/list, /add и /remove, такая же тройка blocked-hosts и POST /api/resident-proxy/rotate-ip, который меняет IP sticky-сессии по port или sessid. Именно белый список заставляет работать Selenium, см. гайд по автоматизации браузера.

6 Проверка работы

Две проверки. Первая: GET /api/me с вашим токеном должен вернуть профиль; 401 значит, что токен истёк или его заменил другой вход. Вторая: возьмите одну строку из ответа proxy-list и прогоните через неё запрос: curl -x http://login:password@host:port https://ipinfo.io/json. Эндпоинт публичный и отвечает IP, который видит. Если это IP прокси, вся цепочка от входа до рабочего прокси в порядке.

Счётчики трафика лежат в POST /api/turbo/usage, POST /api/flex/usage и POST /api/resident-proxy/stats. У планов за IP счётчика трафика нет вовсе, опрашивать там нечего.

7 Какой продукт GeekProxy подходит

API одно на все продукты, так что выбор идёт от задачи, а не от API. Парк парсеров, которому нужны свежие sticky-сессии на каждую задачу, живёт на Residential Turbo или Residential Flex: списки через proxy-list, контроль расхода через usage, докупка через topup. Долгоживущие аккаунты, боты и интеграции с белыми списками сидят на статическом ISP или датацентре IPv4: читаете details, ставите allowed_ip, продлеваете с баланса по расписанию. Мобильные планы используют эндпоинты resident-proxy с теми же вызовами белого списка и ротации. Что бы вы ни выбрали, безоператорная версия сценария всегда одна: сначала баланс, потом покупка или продление с Idempotency-Key.

8 Частые проблемы

401 на токене, который вчера работал

Токены истекают через 86400 секунд, а любой новый вход отзывает старый токен. Ловите 401, входите заново, кешируйте новый токен. Не запускайте два цикла входа на один аккаунт.

400 на topup

Докупка только для трафиковых планов. У shared, dedicated, flawless и ISP гигабайтов нет, их продлевают. Заодно проверьте, что gb целое число от 1 до 500.

Продление отклонено

Нерезидентский план продлевается только пока активен (status_id = 1). После истечения покупайте новый.

Список ISP пустой сразу после buy-isp

Так и должно быть. Выдача асинхронная. Опрашивайте POST /api/isp/proxy-list или чуть позже вызовите POST /api/isp/refresh-instances.

Поиск пакета ломается после изменения каталога

Вы сопоставляли по названию плана. Документация говорит сопоставлять по num. Названия меняются, номера нет.

Пополнение не проходит с оплатой с баланса

Так задумано: пополнить баланс с баланса нельзя. Берите внешний способ и открывайте возвращённый paymentUrl.