快喵节点接口 GET /v1/nodes：96 个节点的字段与筛选口径

节点接口返回平台当前可选的线路清单。按 2026-09-12 至 09-18 的采样口径，96 个节点的平均延迟 118 毫秒、丢包 0.3%、可用率 99.94%。

快喵节点接口用途

节点接口是接入方获取可用线路的入口。它不做任何状态变更，可安全地高频调用，返回值直接对应采样报告中的字段。文档把返回字段与实测统计一一对应：latencyMs 是探测口径的延迟，lossPercent 是丢包率，uptimePercent 是该节点在采样窗口内的可用率。

在 2026-09-12 至 2026-09-18 的采样区间内，96 个节点的整体可用率 99.94%，平均延迟 118 毫秒，丢包率 0.3%。这些是全量口径；加上地区或协议筛选后，返回的是该子集的统计值，样本更小，波动通常更大。

# 不带筛选条件时返回全部 96 个节点
curl -s 'https://api.kuaimapp.com.cn/v1/nodes' \
  -H 'Authorization: Bearer YOUR_TOKEN'

# 按地区与健康度筛选，字段名见参数表
curl -s 'https://api.kuaimapp.com.cn/v1/nodes?region=cn-east&maxLatencyMs=150' \
  -H 'Authorization: Bearer YOUR_TOKEN'

快喵节点接口请求参数

下表列出 GET /v1/nodes 支持的查询参数。所有参数均为可选，不传时返回全量节点；地区参数的合法取值共 22 个，与地区接口返回的列表一致。参数含义与取值范围来自官方文档的参数章节。

地区取值共 22 个；延迟阈值的单位为毫秒，与返回字段口径一致。

六个参数覆盖了筛选、排序与翻页三类需求。以地区与延迟联合筛选为例，region 取值来自 22 个地区代码之一，maxLatencyMs 设为 150 时返回的是该地区中延迟低于 150 毫秒的节点子集，而非全部 96 个节点。

limit 与 cursor 组成翻页机制。采样区间内单次全量查询返回 96 条记录，为控制响应体积，超过 100 条时服务端会要求使用 cursor 翻页；翻页过程中节点可能因健康检查结果变化而移动位置，建议以节点 ID 而非列表下标作为业务主键。

快喵节点接口返回字段

返回体为分页结构，包含 nodes 数组与分页元信息。单个节点对象的字段如下，数值类型均为整数或定点数，不返回字符串形式的数字，便于直接参与计算。

延迟与握手耗时单位为毫秒；比例字段为百分比数值。

字段表中 latencyMs 的示例直接取采样均值 118 毫秒，便于理解量级；实际调用返回的是该节点在该次统计窗口内的取值，不同节点之间差异可能达到数十毫秒。uptimePercent 为 99.94% 是全站整体口径，单个节点的可用率通常高于或低于该值。

from kuai import KuaiClient

client = KuaiClient(token=TOKEN)   # SDK 2.7.0
resp = client.nodes.list(region='cn-east', max_latency_ms=150)

for node in resp.data:
    # 字段口径：latency_ms 毫秒 / loss_percent 百分比
    print(node.id, node.latency_ms, node.loss_percent)

# 采样均值参考：latency 118 毫秒，可用率 99.94%

• 地区取值：region 参数的合法值共 22 个，传入未定义值会返回 400 段错误码而不是空列表，便于及时发现配置错误。
• 延迟阈值：maxLatencyMs 以毫秒为单位，比较对象是采样均值 118 毫秒；设为 150 时筛掉的是高于该阈值的节点。
• 健康度过滤：minUptimePercent 以 99.94% 为基准设置下限，高于该值的节点数在 22 个地区上分布并不均匀。
• 翻页游标：cursor 取自上一页的 nextCursor；翻页期间 96 个节点的健康状态会更新，游标可能指向位置发生变化的记录。
• 调用频率：接口只读不写，可按业务需要调用，但建议在应用侧加 60 秒级缓存，避免频繁请求触发 429 段限流。

五条注意事项对应的都是容易踩的实际问题：地区拼错会拿到错误码而不是空结果，延迟阈值单位写错会静默筛掉全部节点，健康度过滤在不同时段结果不同，翻页游标会因健康状态变化而漂移，调用频率则直接关联限流。