令牌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}，出现在每个按计时器轮换的令牌上。见轮换。

rotateUrl是独享设备的“立即更换IP”链接，仅在令牌可以使用它时出现。它与旁边的密码一样需要保密。

username和password是该令牌的代理凭证。与ingress或控制台中显示的端点配合使用。

用量#

读取一个自有令牌中客户可见的流量。

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

查询参数#

省略时间范围时，API使用当前UTC日之前的30个完整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是非负的十进制字符串，其中freeTotalBytes等于两个方向的值相加。没有缓存遥测数据的历史时段，这些字段报告为零。

仅对PPG令牌，cache.savedCostUnits是一个非负的十进制字符串，表示按流量产生时的有效价格计算、经审计的已避免费用。不限流量令牌会刻意省略该字段，而不是设为0或null，因为没有避免任何按GB计费的客户费用。

令牌必须属于已认证的用户。未知或不属于您的令牌返回相同的404 TOKEN_NOT_FOUND响应。

费用明细#

对于PPG令牌，请求include=charges&groupBy=hour，可在每个小时时间桶中加入已持久化的费用记录。不限流量令牌会拒绝该扩展。带版本的费用记录包含代理池的公开标识和名称、原始及计费的上传/下载字节数、参与的节点和协议、快照的基础/有效费率和折扣，以及实际扣除的确切金额。没有快照的行标记为Legacy PPG usage；API不会根据当前令牌设置来猜测其代理池或费率。

费用明细即计费记录。上传和下载都计费。reserved状态的费用可能会随该小时的延迟流量到达而增加；finished状态的费用是最终的。

域名明细#

请求include=domains，可在data中加入domainBreakdown：

{
  "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天。返回的UTCrange是实际生效的时间桶区间：过去的不完整起点向下取整到所在小时，过去的不完整终点向上取整到下一个小时。被限制为当前时间的终点仍保持为该确切时间，因此响应不会声称覆盖了当前时间之后。区间被调整时，还会报告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，目标位置当前没有可用的IP或设备时为unavailable（令牌保留其最后一个，而不会丢失路由），令牌的套餐未在使用中时为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字段所列出的值。动态数据中心/ISP令牌、标准美国共享设备令牌和美国独享设备的changeable为true。独享设备的options从5分钟起。“多地点”令牌始终报告其当前手机的间隔，且changeable: false，因为代理所在的手机自行设定计时器；对它的PUT也会返回409 NOT_SUPPORTED，其他任何不轮换的令牌也是如此。

轮换错误#

新IP#

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

仅限静态数据中心和ISP令牌。动态令牌每次轮换都会更换IP，没有单一的当前IP可供替换。该请求不带请求体：服务每次尝试（包括重试）都会重用令牌自己已保存的位置。返回与位置相同的结构，其中带有新的effective IP。

这是唯一一个不能盲目重复的写操作。如果响应丢失或超时，重试之前先读取GET /tokens/{tokenId}/location：nextChangeAt晚于当前时间，说明更改已生效。在这一周内再次发送POST不会得到第二个IP；它会返回409 CHANGE_LIMIT。

新IP错误#