API 参考
一组精简的 REST 接口,覆盖控制台中的日常操作:代理用户、用量和白名单。
管理 API 负责账号层面的操作,不承载代理流量。流量按快速开始所述经网关转发;这套 API 用于在代码中创建代理用户、查询用量和维护白名单。
API 目前为草案版本,可以正常使用,但在宣布稳定之前,路径和字段名仍可能调整。若有变动,本页会同步说明。
基本约定
所有请求通过 HTTPS 发往 https://scalardata.ai/api/v1,并以 Bearer 令牌形式携带 API 密钥。密钥在控制台的 API 密钥 页面(/app/api-keys)创建,每个账号最多保留 20 个有效密钥。请求与响应正文均为 JSON。
每个密钥都拥有通过本 API 操作整个账号的全部权限,没有权限范围(scope)之分,也没有只读密钥:持有密钥的人可以创建、修改和删除代理用户,并为其设置新密码。请勿把密钥写进源代码;不再使用的密钥请在控制台中吊销。密钥吊销后,下一个请求起即返回 401。
# ScalarData 管理 API,v1 草案。
# 正式发布前,路径和字段可能调整。
curl https://scalardata.ai/api/v1/proxy-users \
-H "Authorization: Bearer $SCALARDATA_API_KEY"错误使用常规的 HTTP 状态码:正文缺失、不是 JSON 对象或未带 Content-Type: application/json 时返回 400;密钥缺失、不存在或已吊销返回 401;已登录的浏览器会话收到跨站修改请求时返回 403,错误码为 forbidden;代理用户或白名单条目不存在返回 404;名称或地址已被占用返回 409(conflict);输入校验失败、达到数量上限(100 个代理用户、50 个白名单条目)或日期范围、游标无效时返回 422;服务端故障返回 500,错误码为 internal_error。错误正文结构统一:
{
"error": {
"code": "invalid_request",
"message": "network: Invalid option: expected one of \"residential\"|\"isp\"|\"datacenter\"",
"details": [
{
"path": "network",
"message": "Invalid option: expected one of \"residential\"|\"isp\"|\"datacenter\""
}
]
}
}程序里请根据 code 判断错误类型,message 是写给人看的说明。details 只会出现在 422 响应中:字段校验失败时,按 path 列出每个失败的字段。
列表接口通过 limit(1 到 200,默认 50)和 cursor 分页。nextCursor 不为 null 时,将其作为 cursor 传回即可获取下一页。字节数为普通整数,日期为 UTC 时区的 ISO 8601 格式。
账号
GET/account
返回 API 密钥所属账号的余额和订阅信息。handle 是 6 位的账号标识,在每个代理用户名中都位于代理用户名称之前(HANDLE-NAME)。
balance 是住宅流量扣费所用的余额:packBytes 为预付流量包的剩余字节数,creditMicroUsd 为充值余额,freeCreditMicroUsd 为新账号赠送额度的剩余部分;两项金额均以百万分之一美元为单位。账户验证之前,赠送额度记在 lockedFreeCreditMicroUsd 中,不能用于付费;验证后会转入 freeCreditMicroUsd。
请求
GET https://scalardata.ai/api/v1/account
Authorization: Bearer $SCALARDATA_API_KEY响应
{
"id": "0c9b6e2f-7d41-4a8e-b356-9f2e1c7a4d80",
"handle": "k7f3q2",
"email": "[email protected]",
"name": "Acme Data",
"companyName": "Acme Data Inc.",
"locale": "en",
"balance": {
"packBytes": 12884901888,
"creditMicroUsd": 20000000,
"freeCreditMicroUsd": 1250000,
"lockedFreeCreditMicroUsd": 0
},
"subscriptions": [
{
"id": "5a3e8f1c-2b7d-4c96-8e40-d1f6a9b2c735",
"network": "isp",
"tierId": "starter",
"status": "active",
"includedUnits": 10,
"currentPeriodStart": "2026-08-26T00:00:00.000Z",
"currentPeriodEnd": "2026-09-26T00:00:00.000Z",
"cancelAtPeriodEnd": false
}
]
}代理用户
GET/proxy-users
按创建时间先后列出账号下的全部代理用户,可用 network 和 status 过滤。响应不包含密码。
请求
GET https://scalardata.ai/api/v1/proxy-users?limit=50
Authorization: Bearer $SCALARDATA_API_KEY响应
{
"data": [
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"network": "residential",
"status": "active",
"defaultCity": "seoul",
"defaultSessionMinutes": 10,
"trafficCapBytes": 107374182400,
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"lastUsedAt": "2026-09-07T10:19:03.512Z",
"createdAt": "2026-08-14T09:12:41.087Z",
"updatedAt": "2026-09-01T08:30:12.640Z"
},
{
"id": "b2e9c7d4-1a6f-4e38-8c05-3f7a9d2e6b10",
"name": "acme-crawler",
"network": "datacenter",
"status": "active",
"defaultCity": null,
"defaultSessionMinutes": null,
"trafficCapBytes": null,
"whitelist": [
"203.0.113.24"
],
"lastUsedAt": null,
"createdAt": "2026-08-20T16:03:05.411Z",
"updatedAt": "2026-08-20T16:03:05.411Z"
}
],
"nextCursor": null
}POST/proxy-users
创建代理用户。name 和 network 必填,network 取 residential、isp 或 datacenter 之一。不传 password 时系统自动生成并在本次响应中返回,之后也可在控制台点击显示再次查看。自行设置的密码为 16 到 128 位、不含空格和冒号的可打印 ASCII 字符。defaultCity、defaultSessionMinutes 和 trafficCapBytes 可选,trafficCapBytes 为 null 表示不限流量;status(active 或 disabled)同样可选。每个账号最多 100 个代理用户,超出时返回 422。isp、datacenter 代理用户只有在账号拥有该网络的生效订阅时才能传输流量。
在每个代理用户名中,名称都紧跟在账号标识之后。名称长度为 3 到 32 位,由小写字母、数字和连字符组成;连字符不能出现在开头或结尾,也不能连用;以连字符分隔的每一段都不能是保留字:res、isp、dc、country、city、asn、session、sessduration。
请求
POST https://scalardata.ai/api/v1/proxy-users
Authorization: Bearer $SCALARDATA_API_KEY
Content-Type: application/json
{
"name": "acme-staging",
"password": "a-long-random-string",
"network": "residential",
"trafficCapBytes": 5368709120,
"defaultSessionMinutes": 10
}响应
HTTP/1.1 201 Created
{
"id": "d47a0c3e-95b2-4f16-a8e7-0b6c2f9d3a58",
"name": "acme-staging",
"network": "residential",
"status": "active",
"defaultCity": null,
"defaultSessionMinutes": 10,
"trafficCapBytes": 5368709120,
"whitelist": [],
"lastUsedAt": null,
"createdAt": "2026-09-07T10:21:57.302Z",
"updatedAt": "2026-09-07T10:21:57.302Z",
"password": "a-long-random-string"
}GET/proxy-users/{id|name}
返回单个代理用户。路径中填它的 id 或 name 均可。
请求
GET https://scalardata.ai/api/v1/proxy-users/acme-prod
Authorization: Bearer $SCALARDATA_API_KEY响应
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"network": "residential",
"status": "active",
"defaultCity": "seoul",
"defaultSessionMinutes": 10,
"trafficCapBytes": 107374182400,
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"lastUsedAt": "2026-09-07T10:19:03.512Z",
"createdAt": "2026-08-14T09:12:41.087Z",
"updatedAt": "2026-09-01T08:30:12.640Z"
}PATCH/proxy-users/{id|name}
只修改请求中带的字段,其余保持不变。可修改的字段有 name、network、defaultCity、defaultSessionMinutes、trafficCapBytes(设为 null 即取消上限)和 status(active 或 disabled)。密码只能通过 rotate-password 修改。返回修改后的代理用户。
请求
PATCH https://scalardata.ai/api/v1/proxy-users/acme-prod
Authorization: Bearer $SCALARDATA_API_KEY
Content-Type: application/json
{
"trafficCapBytes": 214748364800,
"defaultCity": "busan"
}响应
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"network": "residential",
"status": "active",
"defaultCity": "busan",
"defaultSessionMinutes": 10,
"trafficCapBytes": 214748364800,
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"lastUsedAt": "2026-09-07T10:19:03.512Z",
"createdAt": "2026-08-14T09:12:41.087Z",
"updatedAt": "2026-09-07T10:23:40.218Z"
}DELETE/proxy-users/{id|name}
删除代理用户。使用其用户名的新连接会立即被拒绝。历史用量仍保留在用量报表中,只是 proxyUserId 和 proxyUser 变为 null。该代理用户的白名单地址也会一并删除。
请求
DELETE https://scalardata.ai/api/v1/proxy-users/acme-staging
Authorization: Bearer $SCALARDATA_API_KEY响应
HTTP/1.1 204 No ContentPOST/proxy-users/{id|name}/rotate-password
设置新密码:请求正文带 password(16 到 128 位、不含空格和冒号的可打印 ASCII 字符)时使用该值,不带正文时自动生成。响应包含 id、name、新的 password 和 rotatedAt;API 只在这里返回密码,也可在控制台点击显示再次查看。已建立的连接不受影响,新连接须使用新密码。
请求
POST https://scalardata.ai/api/v1/proxy-users/acme-prod/rotate-password
Authorization: Bearer $SCALARDATA_API_KEY响应
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"password": "another-long-random-string",
"rotatedAt": "2026-09-07T10:24:05.771Z"
}用量
用量是经网关双向中转的字节数,按代理用户和网络分别统计。住宅流量按这些字节计费;ISP 和数据中心流量只用于上限计算和统计。from 与 to 为 UTC 日历日期,首尾均包含。两者都不传时返回最近 30 天:to 默认为今天,from 默认为 to 之前 29 天。单次查询的范围最多 366 天。两个接口都支持两个可选过滤参数:network(residential、isp 或 datacenter)和 proxyUser(代理用户的 ID 或名称),不带时返回账号总量。
除 bytes 外,每行还包含以下计数:
| 字段 | 说明 |
|---|---|
| requests | 到达出口的连接数。按连接而非 HTTP 请求计数,承载多个请求的 HTTPS 隧道只算一次。 |
| successes | 其中成功打开到出口隧道的连接数。 |
| avgLatencyMs | 成功连接从开始连接出口到隧道打开的平均耗时(毫秒);没有成功连接时为 null。仅每日用量行包含此字段。 |
GET/usage/daily
按请求的日期范围,返回每天、每个代理用户、每个网络各一行。已删除代理用户的行仍保留字节数,proxyUserId 和 proxyUser 为 null。
请求
GET https://scalardata.ai/api/v1/usage/daily?from=2026-09-01&to=2026-09-03&proxyUser=acme-prod
Authorization: Bearer $SCALARDATA_API_KEY响应
{
"from": "2026-09-01",
"to": "2026-09-03",
"data": [
{
"date": "2026-09-01",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"proxyUser": "acme-prod",
"network": "residential",
"requests": 48210,
"successes": 48162,
"bytes": 3187654321,
"avgLatencyMs": 214
},
{
"date": "2026-09-02",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"proxyUser": "acme-prod",
"network": "residential",
"requests": 51877,
"successes": 51825,
"bytes": 3420117904,
"avgLatencyMs": 221
},
{
"date": "2026-09-03",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"proxyUser": "acme-prod",
"network": "residential",
"requests": 12046,
"successes": 12034,
"bytes": 801223616,
"avgLatencyMs": 236
}
]
}GET/usage/cities
按城市汇总指定范围内的用量。流量经过的上游标注了城市时计入该城市;通过供应商定向城市时计入所指定的城市;两者都不满足时计入 city 为 null 的行。城市取值与 city- 参数接受的小写名称一致。
请求
GET https://scalardata.ai/api/v1/usage/cities?from=2026-09-01&to=2026-09-03
Authorization: Bearer $SCALARDATA_API_KEY响应
{
"from": "2026-09-01",
"to": "2026-09-03",
"data": [
{
"city": "seoul",
"requests": 71204,
"successes": 71133,
"bytes": 4611686018
},
{
"city": "busan",
"requests": 22913,
"successes": 22890,
"bytes": 1503238553
},
{
"city": "incheon",
"requests": 18016,
"successes": 17998,
"bytes": 1294071270
},
{
"city": null,
"requests": 2310,
"successes": 2302,
"bytes": 157286400
}
]
}白名单
白名单中的地址可免密使用代理用户。网关对白名单的处理方式见认证。
每个白名单条目是一个 IPv4 或 IPv6 地址,或一个不宽于 IPv4 /24、IPv6 /64 的 CIDR 网段,并绑定到一个代理用户。每个账号的所有代理用户合计最多可添加 50 个地址。/whitelist 系列接口返回的条目包含以下字段:
| 字段 | 说明 |
|---|---|
| id | 条目 ID,用于 GET 和 DELETE /whitelist/{id}。 |
| cidr | 按规范写法保存的地址或网段:单个地址不带 /32 或 /128,网段取其网络地址,一律小写。 |
| label | 条目备注,没有时为 null。 |
| proxyUserId | 该地址免密登录时对应的代理用户 ID。 |
| createdAt, updatedAt | UTC 时区的 ISO 8601 时间。 |
GET/proxy-users/{id|name}/whitelist
返回某个代理用户绑定的全部地址(已排序),与代理用户对象中的 whitelist 字段相同。
请求
GET https://scalardata.ai/api/v1/proxy-users/acme-prod/whitelist
Authorization: Bearer $SCALARDATA_API_KEY响应
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"updatedAt": "2026-09-07T10:25:12.904Z"
}PUT/proxy-users/{id|name}/whitelist
用 cidrs 中的地址整体替换某个代理用户的白名单,传空数组即清空。条目可以是 IPv4、IPv6 地址或 CIDR 网段,网段不能宽于 IPv4 /24 或 IPv6 /64。只要其中有地址已绑定到其他代理用户,或与其他账号的地址、网段重叠,整个请求就会返回 409,白名单保持不变;同一账号下各代理用户的网段可以重叠。变更对新建连接立即生效。
请求
PUT https://scalardata.ai/api/v1/proxy-users/acme-prod/whitelist
Authorization: Bearer $SCALARDATA_API_KEY
Content-Type: application/json
{
"cidrs": ["203.0.113.10", "198.51.100.0/24"]
}响应
{
"id": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"name": "acme-prod",
"whitelist": [
"198.51.100.0/24",
"203.0.113.10"
],
"updatedAt": "2026-09-07T10:25:12.904Z"
}GET/whitelist
按添加时间先后列出账号下所有代理用户的白名单条目;传入 proxyUserId(代理用户的 ID 或名称)时只列出该代理用户的条目,若该代理用户不存在或属于其他账号,返回 404。通过 limit 和 cursor 分页。
请求
GET https://scalardata.ai/api/v1/whitelist?limit=50
Authorization: Bearer $SCALARDATA_API_KEY响应
{
"data": [
{
"id": "3e7b9d10-58a2-4c6f-91e4-2d0a6b8c5f37",
"cidr": "198.51.100.0/24",
"label": "office",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"createdAt": "2026-08-14T09:15:02.336Z",
"updatedAt": "2026-08-14T09:15:02.336Z"
},
{
"id": "a41c6e8f-0b3d-4f72-8e95-7c2d1b6a9e04",
"cidr": "203.0.113.24",
"label": null,
"proxyUserId": "b2e9c7d4-1a6f-4e38-8c05-3f7a9d2e6b10",
"createdAt": "2026-08-20T16:04:47.120Z",
"updatedAt": "2026-08-20T16:04:47.120Z"
},
{
"id": "9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63",
"cidr": "203.0.113.10",
"label": "prod-worker-1",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"createdAt": "2026-09-07T10:25:12.904Z",
"updatedAt": "2026-09-07T10:25:12.904Z"
}
],
"nextCursor": null
}POST/whitelist
为某个代理用户添加一个地址或网段:请求正文带 cidr、所属代理用户的 proxyUserId,以及可选的 label。网段不能宽于 IPv4 /24 或 IPv6 /64。地址统一转为规范写法后保存,因此 203.0.113.10/32 与 203.0.113.10 视为同一条目。添加已在白名单中的地址,或与其他账号的地址、网段重叠的地址,会返回 409;同一账号内允许重叠,例如一个代理用户绑定 /24 网段,另一个代理用户绑定其中的 /32 地址。
请求
POST https://scalardata.ai/api/v1/whitelist
Authorization: Bearer $SCALARDATA_API_KEY
Content-Type: application/json
{
"cidr": "203.0.113.10",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"label": "prod-worker-1"
}响应
HTTP/1.1 201 Created
{
"id": "9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63",
"cidr": "203.0.113.10",
"label": "prod-worker-1",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"createdAt": "2026-09-07T10:25:12.904Z",
"updatedAt": "2026-09-07T10:25:12.904Z"
}DELETE/whitelist
按查询参数中的 id 或 cidr 删除一个条目。
请求
DELETE https://scalardata.ai/api/v1/whitelist?cidr=203.0.113.10
Authorization: Bearer $SCALARDATA_API_KEY响应
HTTP/1.1 204 No ContentGET/whitelist/{id}
按 id 返回单个白名单条目。
请求
GET https://scalardata.ai/api/v1/whitelist/9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63
Authorization: Bearer $SCALARDATA_API_KEY响应
{
"id": "9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63",
"cidr": "203.0.113.10",
"label": "prod-worker-1",
"proxyUserId": "6f1d8a52-3c4e-4b7a-9d21-58e0c7b4a913",
"createdAt": "2026-09-07T10:25:12.904Z",
"updatedAt": "2026-09-07T10:25:12.904Z"
}DELETE/whitelist/{id}
按 id 删除单个白名单条目。此后来自该地址的新连接都需要提供密码。
请求
DELETE https://scalardata.ai/api/v1/whitelist/9c2f4b1e-6d3a-4e85-b7f0-1a5c8e2d4f63
Authorization: Bearer $SCALARDATA_API_KEY响应
HTTP/1.1 204 No Content