跳至正文

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 Content

POST/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, updatedAtUTC 时区的 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 Content

GET/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