API токенов

Все токены прокси: список, чтение и использование. У безлимитных токенов, которые можно перемещать, есть также местоположение, ротация и новый IP по запросу.

Список и чтение#

GET /api/v1/tokens
Authorization: Bearer lit_...

Результаты упорядочены от новых к старым. Запрашивайте возвращаемый page.nextCursor, пока он не станет null.

GET /api/v1/tokens/{tokenId}
Authorization: Bearer lit_...

Возвращает один токен в той же форме, что и элемент списка GET /tokens, включая его username и password. Неизвестный, чужой или не поддающийся разбору tokenId даёт 404 TOKEN_NOT_FOUND; ответ никогда не раскрывает токен другого пользователя.

Примеры#

Безлимитный токен серверных прокси в пакете с разрешёнными IP и изменяемым местоположением:

{
  "id": 12345,
  "type": "unlimited",
  "status": "active",
  "label": "Production crawler",
  "createdAt": "2026-08-01T10:15:00.000Z",
  "expiresAt": "2026-12-01T00:00:00.000Z",
  "ingress": {
    "hub": "us-11",
    "protocol": "http",
    "mode": "assigned",
    "host": "hub-us-11-1.litport.net",
    "port": 31337,
    "status": "available"
  },
  "packageId": 45,
  "ipAuth": { "host": "hub-us-11-1.litport.net", "port": 31338 },
  "location": { "country": "us", "region": "new-york", "city": "new-york-city" },
  "rotation": { "intervalSec": 600, "options": [600, 1800, 3600], "changeable": true },
  "username": "proxy-username",
  "password": "proxy-password"
}

Токен с оплатой за ГБ, привязанный к одному пулу:

{
  "id": 12399,
  "type": "ppg",
  "status": "active",
  "label": "Residential crawler",
  "createdAt": "2026-08-01T10:15:00.000Z",
  "expiresAt": null,
  "ingress": {
    "hub": "example-hub",
    "protocol": "http",
    "mode": "request-selected",
    "supportedProtocols": ["http", "https", "socks5"]
  },
  "poolSelection": {
    "mode": "fixed",
    "pool": { "authKey": "residential-main", "name": "Residential Main" }
  },
  "packageId": null,
  "ipAuth": null,
  "username": "proxy-username",
  "password": "proxy-password"
}

Идентификаторы и хабы в примерах этой документации условные.

Семантика полей#

type — ppg или unlimited. status — собственный жизненный цикл токена: disabled, если он явно отключён, иначе expired, если срок его действия истёк, иначе active. Значение hub-unavailable здесь не встречается; оно относится к ingress.status, см. ниже.

У токена PPG ingress.mode равен request-selected: единого хоста и порта нет, потому что хаб, протокол и пул выбираются для каждого запроса или экспорта. ingress.hub и ingress.protocol — предпочтения личного кабинета и экспорта, а ingress.supportedProtocols перечисляет доступные варианты. Хост берите из hubs пула, а порт — из его httpPort/socks5Port (см. Оплата за ГБ).

У безлимитного токена ingress.mode равен assigned: токен соответствует ровно одному эндпоинту, который всегда сообщается как ingress.host и ingress.port. ingress.status — available или hub-unavailable. hub-unavailable означает, что токен указывает на хаб, который больше не работает: ingress.host и ingress.port тогда равны null, и данные для подключения нельзя использовать, пока поддержка не переведёт токен на действующий хаб.

packageId — публичный числовой ID пакета, если токен принадлежит вашему пакету, иначе null; читайте пакет через Пакеты. ipAuth — это {host, port}, эндпоинт токена без пароля, либо null, если сейчас его у токена нет. Он принимает подключения только с разрешённых IP пакета.

location есть только у токена, местоположение которого можно менять; какие токены подходят, перечислено в разделе Местоположение. Форма зависит от вида: токен серверных или ISP-прокси сообщает {country, region, city}; мобильный токен — {country, city, carrier}.

rotation — {intervalSec, options, changeable}, присутствует у каждого токена, который меняет IP по таймеру. См. Ротация.

rotateUrl — ссылка «сменить IP сейчас» для «Выделенного устройства», присутствует только тогда, когда токен может её использовать. Считайте её такой же секретной, как пароль рядом с ней.

username и password — данные для подключения к прокси для этого токена. Используйте их с эндпоинтом из ingress или личного кабинета.

Использование#

Читайте трафик, видимый клиенту, для одного вашего токена.

GET /api/v1/tokens/{tokenId}/usage
Authorization: Bearer lit_...

Параметры запроса#

Если диапазон не указан, API использует 30 полных суток UTC перед текущим днём UTC. Диапазоны по часам ограничены 31 днём, по дням — 366 днями, по месяцам — 36 месяцами.

Пример#

curl --get 'https://litport.net/api/v1/tokens/12345/usage' \
  -H "Authorization: Bearer $LITPORT_API_KEY" \
  --data-urlencode 'from=2026-08-01T00:00:00Z' \
  --data-urlencode 'to=2026-08-03T00:00:00Z' \
  --data-urlencode 'groupBy=day'

{
  "data": {
    "tokenId": 12345,
    "range": {
      "from": "2026-08-01T00:00:00.000Z",
      "to": "2026-08-03T00:00:00.000Z",
      "groupBy": "day",
      "timezone": "UTC"
    },
    "trafficBasis": "customer_chargeable",
    "summary": {
      "requests": 42,
      "uploadedBytes": "12000",
      "downloadedBytes": "88000",
      "totalBytes": "100000",
      "cache": {
        "hits": 12,
        "misses": 4,
        "bypasses": 2,
        "hitRate": 0.75,
        "freeUploadedBytes": "0",
        "freeDownloadedBytes": "24000",
        "freeTotalBytes": "24000",
        "savedCostUnits": "0.0324"
      }
    },
    "buckets": [
      {
        "start": "2026-08-01T00:00:00.000Z",
        "end": "2026-08-02T00:00:00.000Z",
        "requests": 42,
        "uploadedBytes": "12000",
        "downloadedBytes": "88000",
        "totalBytes": "100000",
        "cache": {
          "hits": 12,
          "misses": 4,
          "bypasses": 2,
          "hitRate": 0.75,
          "freeUploadedBytes": "0",
          "freeDownloadedBytes": "24000",
          "freeTotalBytes": "24000",
          "savedCostUnits": "0.0324"
        }
      }
    ]
  }
}

Семантика использования#

Интервал полуоткрытый: [from, to). Бакеты упорядочены по времени начала и разрежены; отсутствие бакета означает, что сохранённой агрегированной строки нет, а не ошибку API.

У токенов PPG trafficBasis равен customer_chargeable, поэтому итоги трафика совпадают с трафиком, который видит клиент. У токенов с фиксированной ценой (безлимитных) он равен observed; их существующие итоги трафика остаются основой наблюдаемой передачи. Большие итоги в байтах — десятичные строки, чтобы клиенты могли сохранить точные значения. requests — целое число JSON.

Выгода от кеша#

Каждый бакет и сводка содержат cache. hits, misses и bypasses — целые числа JSON; hitRate равен hits / (hits + misses) и равен 0, если не было ни попаданий, ни промахов. freeUploadedBytes, freeDownloadedBytes и freeTotalBytes — неотрицательные десятичные строки (основание 10), причём freeTotalBytes равно сумме двух значений по направлениям. Для старых периодов без телеметрии кеша в этих полях возвращаются нули.

Только у токенов PPG cache.savedCostUnits — неотрицательная десятичная строка (основание 10) с проверенной суммой списания, которого удалось избежать, по цене, действовавшей на момент трафика. У безлимитных токенов поле намеренно отсутствует, а не равно 0 или null, потому что списание за ГБ с клиента не было предотвращено.

Токен должен принадлежать аутентифицированному пользователю. Неизвестный или чужой токен возвращает тот же ответ 404 TOKEN_NOT_FOUND.

Разбивка списаний#

Для токена PPG запросите include=charges&groupBy=hour, чтобы добавить сохранённое списание в каждый почасовой бакет. Для безлимитных токенов такое расширение отклоняется. Версионное списание содержит публичный ключ и название пула, исходные и тарифицируемые отправленные и полученные байты, участвовавшие хабы и протоколы, сохранённые на момент списания базовый и действующий тарифы и скидку, а также точную списанную сумму. Строка без таких снимков помечена Legacy PPG usage; API не угадывает её пул или тариф по текущим настройкам токена.

Компоненты списания — это запись тарификации. Тарифицируются и отправка, и получение. Списание reserved может расти, пока приходит запоздавший трафик за этот час; списание finished окончательное.

Разбивка по доменам#

Запросите include=domains, чтобы добавить domainBreakdown в data:

{
  "domainBreakdown": {
    "limit": 150,
    "totalDestinationCount": 151,
    "displayedCount": 150,
    "truncated": true,
    "range": {
      "from": "2026-08-01T00:00:00.000Z",
      "to": "2026-08-03T00:00:00.000Z",
      "timezone": "UTC",
      "periodClamped": false,
      "endClamped": false
    },
    "items": [{
      "protocol": "tcp",
      "destination": "example.com",
      "port": 443,
      "requests": 42,
      "uploadedBytes": "12000",
      "downloadedBytes": "88000",
      "totalBytes": "100000",
      "lastSeenAt": "2026-08-01T12:00:00.000Z",
      "firstSeenAt": "2026-08-01T00:00:00.000Z"
    }],
    "other": {
      "protocol": null,
      "destination": "Other",
      "port": null,
      "requests": 1,
      "uploadedBytes": "1",
      "downloadedBytes": "2",
      "totalBytes": "3",
      "lastSeenAt": null,
      "firstSeenAt": null
    }
  }
}

Ответ содержит не более 150 адресов назначения с наибольшим суммарным трафиком. Все остальные адреса назначения и переполнение телеметрии объединяются в other; truncated сообщает, что такое объединение произошло. Для TCP requests — число успешных запросов, а для UDP requests — входящие датаграммы. Данные по доменам хранятся в бакетах по целым часам UTC и ограничены последними 31 днём запрошенного интервала. Возвращаемый range в UTC — фактический интервал бакетов: частичное начало в прошлом округляется вниз до часа, а частичный конец в прошлом — вверх до следующего часа. Конец, ограниченный текущим временем, остаётся ровно на этом времени, поэтому ответ не заявляет покрытие за пределами текущего времени. Когда диапазон скорректирован, он также сообщает periodClamped или endClamped.

Местоположение#

Токен серверных или ISP-прокси, а также мобильный токен, у которого можно менять город или оператора, сообщают поле location и поддерживают этот API. Какие токены подходят и как ведёт себя смена:

GET /api/v1/tokens/{tokenId}/location
Authorization: Bearer lit_...

{
  "data": {
    "tokenId": 12345,
    "kind": "datacenter",
    "mode": "rotating",
    "target": { "country": "us", "region": "new-york", "city": "new-york-city" },
    "effective": {
      "country": "us", "region": "new-york", "city": "new-york-city",
      "labels": { "region": "New York", "city": "New York City" }
    },
    "status": "ready",
    "canChangeNow": true,
    "nextChangeAt": null
  }
}

kind — datacenter, isp или mobile. mode — rotating или static. target — сохранённый выбор; у серверного/ISP-токена region/city могут быть "any". effective — фактическое местоположение IP, который токен держит прямо сейчас, или null, если оно пока неизвестно. status равен pending на короткое время, пока изменение распространяется, ready — когда оно распространилось, unavailable — когда в целевом местоположении сейчас нет пригодного IP или устройства (токен сохраняет последний, а не теряет маршрут), package-inactive — когда пакет токена не активен, либо allowance-exhausted — только для более старого пакета «Мультилокация», у которого ещё есть лимит трафика.

Список доступных местоположений#

GET /api/v1/tokens/{tokenId}/location/options?level=region
GET /api/v1/tokens/{tokenId}/location/options?level=city&region=new-york

Серверные/ISP: level=region, затем level=city&region=…. Мобильные: level=city, затем level=carrier&city=…. Каждый вариант имеет вид {"value": …, "label": …}, а список содержит только те варианты, которые этот токен может использовать прямо сейчас.

Смена местоположения#

Серверные/ISP:

curl -X PUT 'https://litport.net/api/v1/tokens/12345/location' \
  -H "Authorization: Bearer $LITPORT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"region": "new-york", "city": "new-york-city"}'

Мобильные:

curl -X PUT 'https://litport.net/api/v1/tokens/98765/location' \
  -H "Authorization: Bearer $LITPORT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"city": "seattle", "carrier": "verizon"}'

Отправляйте ровно те поля, которые соответствуют виду токена: для серверного/ISP — region и city; для мобильного — city и carrier. country необязателен и при отправке должен быть "us". Заголовок предусловия не требуется и не учитывается: последний зафиксированный PUT становится желаемой целью токена, а PUT, совпадающий с текущей сохранённой целью, выполняется успешно без нового изменения.

Серверный/ISP-токен с ротацией сразу переходит на подходящий IP. Статический получает новый IP в выбранном местоположении, расходуя свой недельный лимит; повтор в пределах той же недели даёт 409 CHANGE_LIMIT с nextChangeAt. Токен «Мультилокация» переходит сразу, без ожидания. Стандартный общий мобильный токен США можно менять раз в 48 часов; повтор в этом окне также даёт 409 CHANGE_LIMIT.

У любого мобильного токена город сохраняется всегда: если у выбранного оператора в этом городе нет рабочего телефона, прокси вместо него использует другого оператора в том же городе, а effective показывает оператора, который реально используется.

Ошибки местоположения#

Ротация#

PUT /api/v1/tokens/{tokenId}/rotation
Authorization: Bearer lit_...
Content-Type: application/json

{"intervalSec": 600}

{
  "data": { "tokenId": 12345, "intervalSec": 600, "options": [600, 1800, 3600], "changeable": true }
}

intervalSec должен быть одним из options — тех же значений, которые перечисляет поле rotation самого токена. changeable равен true для серверного/ISP-токена с ротацией, стандартного общего мобильного токена США и «Выделенного устройства» США. У «Выделенного устройства» options начинаются с 5 минут. Токен «Мультилокация» всегда сообщает интервал своего текущего телефона с changeable: false, потому что телефон, на котором работает прокси, сам задаёт свой таймер; его PUT также отвечает 409 NOT_SUPPORTED, как и любой другой токен без ротации.

Ошибки ротации#

Новый IP#

POST /api/v1/tokens/{tokenId}/new-ip
Authorization: Bearer lit_...

Только статические токены серверных и ISP-прокси. Токен с ротацией и так меняет IP при каждой ротации, и единого текущего IP, который можно заменить, у него нет. Запрос не принимает тело: сервис при каждой попытке, включая повтор, использует сохранённое местоположение самого токена. Возвращает ту же форму, что и Местоположение, с новым IP в effective.

Это единственная запись, которую небезопасно повторять вслепую. Если ответ потерян или истёк по тайм-ауту, прочитайте GET /tokens/{tokenId}/location перед повтором: nextChangeAt позже текущего времени означает, что смена прошла. Повторная отправка POST в течение этой недели не даст второй IP; она вернёт 409 CHANGE_LIMIT.

Ошибки нового IP#