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",
  "disabledReason": null,
  "label": "Production crawler",
  "externalRef": null,
  "createdAt": "2026-08-01T10:15:00.000Z",
  "expiresAt": "2026-12-01T00:00:00.000Z",
  "allowanceBytes": null,
  "allowanceReservedBytes": null,
  "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",
  "disabledReason": null,
  "label": "Residential crawler",
  "externalRef": "customer-1042",
  "createdAt": "2026-08-01T10:15:00.000Z",
  "expiresAt": "2026-12-31T23:59:59.999Z",
  "allowanceBytes": 5000000000,
  "allowanceReservedBytes": 1200000000,
  "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 — active, expired или disabled. Значение hub-unavailable здесь не встречается; оно относится к ingress.status, см. ниже.

disabledReason объясняет, почему токен не пропускает трафик. Пока status равен active, он равен null.

Фильтр status в GET /tokens выбирает токены только по их собственному переключателю вкл/выкл и по сроку действия. Он не находит токен, который disabled из-за allowance или balance, поэтому читайте disabledReason в результатах.

externalRef — ваша собственная ссылка на прокси с оплатой за ГБ или null. expiresAt — момент, когда токен перестаёт работать, или null. allowanceBytes — лимит трафика в байтах или null, если лимита нет, а allowanceReservedBytes — какая часть лимита зарезервирована на данный момент, или null, если лимита нет.

У токена 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 «Выделенного устройства» или серверного/ISP-токена с ротацией, присутствует только тогда, когда она у токена есть. Берегите её так же, как пароль рядом с ней. См. Ссылка для смены IP ниже и Смена IP о способах получить новый IP.

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

Если в аккаунте включён параметр Использовать нейтральные адреса, имена хостов, которые возвращает этот API (ingress.host, ipAuth.host), authKey пула и ссылка rotateUrl содержат нейтральные имена. Имя пула, которое вы передаёте, принимается в любой из двух форм. Для HTTPS-прокси используйте ingress.httpsHost (безлимитный токен с протоколом http): сертификат выдан на это имя. Это собственное имя хаба, и оно совпадает с ingress.host, если только аккаунт не использует нейтральные адреса. Для токена с оплатой за ГБ берите httpsHostname из hubs пула.

Создание и управление прокси#

Прокси с оплатой за ГБ можно создавать, изменять и удалять через API, а данные для подключения любого вашего прокси можно перевыпустить. Форма прокси с оплатой за ГБ в личном кабинете подчиняется тем же правилам. Для каждого вызова здесь нужен API-ключ Bearer, а записи учитываются в ограничении ключа — 120 запросов за 60 секунд.

Прокси пакета принадлежат своему пакету: он создаёт и завершает их, включает и выключает. Для них можно изменить метку и перевыпустить данные для подключения, больше ничего.

Перепродажа разрешена на любом аккаунте. Вы отвечаете за то, как ваши клиенты используют свои прокси: злоупотребление одного из них может заблокировать весь ваш аккаунт.

Создание прокси#

POST /api/v1/tokens
Authorization: Bearer lit_...
Content-Type: application/json

Отправьте JSON-объект, как минимум {}. Запрос без тела ничего не создаёт.

curl -X POST 'https://litport.net/api/v1/tokens' \
  -H "Authorization: Bearer $LITPORT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"pool": "residential-main", "label": "Residential crawler", "externalRef": "customer-1042", "expiresAt": "2026-12-31", "allowanceBytes": 5000000000}'

Ответ — 201 и прокси в форме, показанной в разделе Примеры, с его username и password. Соберите логин прокси из них, как описано в разделе Параметры прокси с оплатой за ГБ.

Всегда передавайте externalRef. Это ваша собственная ссылка, например ID клиента или номер заказа. Создание, повторяющее уже используемый вами externalRef, отвечает 200 с этим прокси и ничего не меняет, даже если остальное тело отличается. Поэтому, если создание завершилось тайм-аутом или вы потеряли ответ, отправьте его снова с тем же externalRef и получите уже существующий прокси. Без externalRef повтор может создать второй прокси. Удалённый прокси освобождает свой externalRef, поэтому его можно использовать снова.

Для создания нужен положительный баланс (INSUFFICIENT_BALANCE) и аккаунт, который не заблокирован (ACCOUNT_BANNED). В аккаунте может быть ограниченное число прокси с оплатой за ГБ (TOKEN_LIMIT_REACHED); чтобы увеличить его, обратитесь в поддержку.

Аккаунт может создавать 60 новых прокси в минуту; считаются вместе все его API-ключи и личный кабинет. Повтор уже используемого externalRef в счёт не идёт. Сверх лимита создание отвечает 429 RATE_LIMITED с Retry-After, и ничего не создаётся: отправьте тот же запрос снова после ожидания.

Изменение прокси#

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

Отправляйте только те поля, которые хотите изменить, и хотя бы одно. Пропущенное поле остаётся как есть. null очищает label, pool, expiresAt и allowanceBytes.

Ответ — 200 и прокси в его текущем состоянии. Тело, которое ничего не меняет, ничего не записывает. Новый пул применяется к новым соединениям; открытые соединения остаются на том пуле, с которого начались, и тарифицируются по его цене.

Выключение, смена метки, смена срока действия или лимита работают всегда, даже при пустом балансе, так что клиента можно отключить в любой момент. То же относится к перевыпуску данных для подключения и к удалению. Для прокси пакета единственное поле — label; любое другое даёт 400 FIELD_NOT_ALLOWED.

Перевыпуск данных для подключения#

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

{"requestId": "reissue-2026-11-04-a"}

Выдаёт новые логин, пароль и ключ смены IP для любого вашего прокси — с оплатой за ГБ или из пакета. Ответ — 200 и прокси в форме, показанной в разделе Примеры, с новыми username и password и новым rotateUrl, если он у прокси есть. Тело необязательно.

• Старый пароль перестаёт работать, а его открытые соединения закрываются.
• Старая ссылка для смены IP перестаёт работать.
• Разрешённые IP пакета продолжают работать, и их соединения остаются открытыми. Разрешённые IP относятся ко всему пакету, а не к одному прокси, поэтому перевыпуск данных для одного прокси не может отключить клиента, который подключается с разрешённого IP. Делите пакет между клиентами только с помощью паролей.

requestId — от 1 до 64 символов: буквы, цифры, подчёркивание или дефис. Используйте новый requestId для каждого перевыпуска, который вам нужен. Отправляйте тот же только для повтора вызова, на который вы не получили ответа: повтор возвращает данные для подключения, выданные первым вызовом, и ничего нового не выдаёт — независимо от того, завершился ли первый вызов или ещё выполняется. Без requestId каждый вызов выдаёт новую пару, поэтому не повторяйте его вслепую.

Удаление прокси#

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

Удаляет прокси с оплатой за ГБ. Ответ — 204 без тела. Прокси перестаёт работать, а его открытые соединения закрываются. История остаётся: использование многих токенов по-прежнему его перечисляет с пометкой deleted, а GET /tokens/{tokenId}/usage по-прежнему отвечает по нему. GET /tokens и GET /tokens/{tokenId} его больше не возвращают. Удаление уже удалённого прокси снова даёт 204.

Прокси пакета удалить нельзя: 409 NOT_SUPPORTED. Он завершается вместе со своим пакетом.

Лимит трафика#

У прокси с оплатой за ГБ может быть лимит трафика allowanceBytes — наибольший объём трафика, который он может израсходовать, в байтах (1 ГБ — это 1,000,000,000 байт). С его помощью можно выдать каждому клиенту, участнику команды или инструменту фиксированный объём. Лимит необязателен. В личном кабинете это поле Лимит трафика (ГБ) у прокси.

• Что учитывается. Весь трафик между клиентом и хабом в обоих направлениях, включая служебные данные протокола. Поэтому лимит никогда не меньше оплачиваемого трафика в использовании: прокси никогда не получает больше оплачиваемого трафика, чем его лимит.
• Где он останавливается. Прокси может остановиться немного не дойдя до лимита, но никогда не превышает его. Litport резервирует трафик для прокси заранее, и неиспользованное не возвращается.
• allowanceReservedBytes. Какая часть лимита зарезервирована на данный момент. Это не то же число, что оплачиваемое использование: оно может опережать переданный трафик и никогда не вычитается из того, что вам списывается. Оплачиваемый трафик читайте в использовании.
• Тарификация не меняется. Лимит только отклоняет трафик.
• Когда лимит исчерпан. status равен disabled, disabledReason равен allowance, а новые соединения получают ошибку прокси 24 (HTTP 403). Увеличьте или снимите лимит, чтобы снова пользоваться прокси.
• Изменение лимита. Добавление, увеличение, уменьшение или снятие лимита один раз завершает открытые соединения прокси; клиенты переподключаются с новым лимитом. Лимит, уменьшенный ниже уже зарезервированного объёма, останавливает прокси, как только будет израсходован уже зарезервированный трафик. Ничего не возвращается.

Ошибки записи прокси#

У каждого кода есть отдельный заголовок на странице Ошибки API.

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

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

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,
    "deleted": false,
    "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. Удалённый токен всё равно отвечает, с deleted: true, чтобы последний счёт клиента можно было прочитать, когда прокси уже нет.

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

Для токена 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.

Использование многих токенов#

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

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

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

Если диапазон не указан, API использует 30 полных суток UTC перед текущим днём UTC. Диапазон ограничен 92 днями (больше — 400 INVALID_TIME_RANGE); более длинный период читайте несколькими вызовами. Этот вызов ограничен 10 запросами за 60 секунд на один API-ключ (429 RATE_LIMITED), и заголовки RateLimit-* и Retry-After сообщают именно об этом ограничении.

Пример списка использования#

curl --get 'https://litport.net/api/v1/usage' \
  -H "Authorization: Bearer $LITPORT_API_KEY" \
  --data-urlencode 'from=2026-10-01T00:00:00Z' \
  --data-urlencode 'to=2026-10-03T00:00:00Z' \
  --data-urlencode 'tokenIds=12399,12400'

{
  "data": {
    "range": {
      "from": "2026-10-01T00:00:00.000Z",
      "to": "2026-10-03T00:00:00.000Z",
      "groupBy": "day",
      "timezone": "UTC"
    },
    "tokens": [
      {
        "tokenId": 12399,
        "type": "ppg",
        "deleted": false,
        "label": "Residential crawler",
        "externalRef": "customer-1042",
        "trafficBasis": "customer_chargeable",
        "summary": {
          "requests": 42,
          "uploadedBytes": "12000",
          "downloadedBytes": "88000",
          "totalBytes": "100000",
          "costUnits": "0.00045"
        },
        "buckets": [
          {
            "start": "2026-10-01T00:00:00.000Z",
            "end": "2026-10-02T00:00:00.000Z",
            "requests": 42,
            "uploadedBytes": "12000",
            "downloadedBytes": "88000",
            "totalBytes": "100000",
            "costUnits": "0.00045"
          }
        ]
      },
      {
        "tokenId": 12400,
        "type": "ppg",
        "deleted": true,
        "label": null,
        "externalRef": "customer-0977",
        "trafficBasis": "customer_chargeable",
        "summary": {
          "requests": 0,
          "uploadedBytes": "0",
          "downloadedBytes": "0",
          "totalBytes": "0",
          "costUnits": "0"
        },
        "buckets": []
      }
    ]
  },
  "page": { "nextCursor": null }
}

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

Страница содержит до limit прокси, сначала новые, у каждого — summary за диапазон и по одному бакету на каждые сутки UTC, в которые был трафик. Интервал полуоткрытый, [from, to), а бакеты разрежены, как и для одного токена. Запрашивайте page.nextCursor, пока он не станет null; на странице может быть меньше limit прокси, потому что удалённые прокси без использования пропускаются.

Данные для подключения здесь никогда не появляются. trafficBasis, строки с байтами и requests означают то же, что и для одного токена. В этом списке нет выгоды от кеша, разбивки по доменам и почасовых списаний; читайте их через GET /tokens/{tokenId}/usage.

costUnits — списанная сумма в единицах баланса, десятичная строка. У прокси с оплатой за ГБ она есть за каждые сутки и в его summary; costUnits бакета равна null для суток с трафиком, но без записанного пока списания, а списание за ещё идущий час может измениться. Для прокси пакета, за который не берётся плата по ГБ, значение равно null.

Удалённые прокси перечисляются с deleted: true и тем externalRef, который у них был. Удалённый прокси без использования в диапазоне появляется только тогда, когда вы указали его в tokenIds. Существующий прокси с оплатой за ГБ присутствует всегда. Прокси пакета присутствует, если только его срок не истёк до from.

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

Токен серверных или 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 — когда оно распространилось, package-inactive — когда пакет токена не активен, либо allowance-exhausted — только для более старого пакета «Мультилокация», у которого ещё есть лимит трафика. Токен серверного или ISP-прокси сообщает ещё два значения, исходя из того, где его IP прямо сейчас:

• fallback: прокси работает на IP вне сохранённого местоположения, потому что в нём не было свободного IP. Прокси с ротацией возвращается сам, когда там появляется свободный IP. Статический остаётся на месте, пока вы не вернёте его, потому что IP, который меняется без запроса, сломал бы списки разрешённых IP на сайтах, где он используется.
• unavailable: IP прокси сейчас не работает; его переносят на рабочий, обычно это занимает несколько минут.

fallback — более новое значение, поэтому клиент, который ветвится по status, должен его обрабатывать. У мобильного токена unavailable по-прежнему означает, что в целевом местоположении сейчас нет рабочего устройства (токен сохраняет последнее, а не теряет маршрут).

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

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

Пусть сервер выберет сам, для любого вида токена:

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

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

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

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

{"random": true} отправляется отдельно, без других полей. Сервер выбирает местоположение, которое этот прокси может использовать прямо сейчас, из тех же значений, что показывает Список доступных местоположений: другой город, если он есть, а для мобильного прокси, если его город единственный, — другого оператора в том же городе. Текущий target прокси не выбирается никогда. Выбор сохраняется как цель, как и любое другое изменение, с теми же проверками и теми же ожиданиями (статический серверный/ISP-прокси расходует недельный лимит, стандартный общий мобильный прокси США — 48-часовой, а CHANGE_LIMIT несёт nextChangeAt, как обычно), а target в ответе показывает, куда переехал прокси. Если у выбранного местоположения нет свободного IP или рабочего телефона, пробуется следующее — до трёх. Если другого местоположения нет или ни одно из трёх не может принять прокси, ответ — 409 LOCATION_UNAVAILABLE, и ничего не меняется.

Случайную смену нельзя слепо повторять: когда ожидание не действует, каждый повтор снова перемещает прокси. После потерянного ответа прочитайте GET /tokens/{tokenId}/location, прежде чем отправлять запрос снова.

Возврат в сохранённое местоположение#

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

Для статического серверного или ISP-токена, у которого status равен fallback: запрос берёт свободный IP в сохранённом местоположении, с теми же хостом, портом, логином и паролем. Это бесплатно: недельный лимит не расходуется, а сохранённая цель target не меняется. Запрос не принимает тело (пустой {} допускается). Возвращает ту же форму, что и Местоположение, с новым IP в effective. IP меняется, поэтому список разрешённых IP на целевом сайте, в котором был старый IP, перестаёт совпадать.

У токена с ротацией такого запроса нет: он возвращается сам, когда в его сохранённом местоположении есть свободный IP. Любой другой токен отвечает 409 NOT_SUPPORTED.

Повтор после успеха даёт 409 NOT_IN_FALLBACK и не выдаёт второй IP, поэтому запрос безопасно отправить снова после потерянного ответа.

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

Ротация#

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 начинаются с 2 минут. Токен «Мультилокация» всегда сообщает интервал своего текущего телефона с changeable: false, потому что телефон, на котором работает прокси, сам задаёт свой таймер; его PUT также отвечает 409 NOT_SUPPORTED, как и любой другой токен без ротации.

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

Новый IP#

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

Кнопка Получить новый IP у прокси в личном кабинете и ссылка для смены IP токена — способы сделать то же без кода; см. Смена IP. Этот эндпоинт охватывает только токены серверных и ISP-прокси. «Выделенное устройство» меняет IP по своей ссылке для смены IP. Запрос не принимает тело. Новый IP остаётся в сохранённом местоположении токена. Токен, у которого status равен fallback или unavailable (вне своего местоположения или на IP, который перестал работать), получает IP в сохранённом местоположении, если там есть свободный, а иначе в том же регионе, затем в любом месте США. Возвращает ту же форму, что и Местоположение, с новым IP в effective.

Статический токен расходует свой недельный лимит. Сервис при каждой попытке, включая повтор, использует сохранённое местоположение самого токена.

Токен с ротацией получает новый IP в любое время. Новый IP всегда отличается от текущего, а автоматический таймер запускается заново: следующая автоматическая смена наступит через rotation.intervalSec секунд после этой. Новые соединения используют новый IP примерно через 5 секунд; открытые соединения сохраняют старый IP, пока не переподключатся. Между двумя запросами должно пройти не меньше наименьшего значения rotation.options токена; повтор внутри этого ожидания даёт 409 CHANGE_LIMIT.

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

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

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

Ссылка для смены IP#

rotateUrl меняет IP без API-ключа: отправьте на неё GET из скрипта или приложения либо откройте в браузере. Ссылка, открытая как страница во вкладке браузера, показывает короткую страницу на языке пользователя. Любой другой клиент получает JSON ниже, а &format=json всегда возвращает JSON, например для приложения, которое управляет настоящим браузером. Любой, у кого есть ссылка, может сменить IP, поэтому берегите её так же, как пароль. Сбросить рядом со ссылкой в личном кабинете создаёт новую ссылку, а старая сразу перестаёт работать. У серверного/ISP-токена с ротацией действуют те же правила, что и у POST /tokens/{tokenId}/new-ip выше: ожидание между сменами, новый IP в сохранённом местоположении и перезапуск таймера. Смена IP — руководство по ссылке и кнопке. Каждый ответ JSON — HTTP 200 с телом из этой таблицы: