仪表盘 API

通过仪表盘 API 以程序化方式访问 Oxylabs 代理用户，用于跟踪使用统计。

该 仪表板API 允许你 以编程方式访问你的产品使用统计数据 并将这些指标集成到你的内部系统中。这样你无需使用网页上的 Oxylabs 仪表板，即可实现自动化报告和实时使用监控。

注意： 仪表板API 目前支持 数据中心代理 (DC) 和 无头浏览器 (HB)。你还可以跟踪 住宅代理, 移动代理, 网页解锁器，以及 网页爬虫API 的使用统计数据，只需简单的 API 请求即可。

所有 API 请求都通过以下基础路径：

https://api.oxylabs.io/

身份验证

重要： 要获取你的仪表板API 密钥，请联系我们的 客户支持 团队。提出请求后，该密钥将在一个工作日内生成并直接提供给你。

你必须在每个请求的 Authorization 请求头中使用 Bearer 方案包含该密钥。

Authorization: Bearer {YOUR_API_KEY}

端点

仪表板API 包含用于产品实例发现和使用统计的端点。所有响应均以 JSON 格式返回。

端点	说明
实例发现	该请求返回你的账户有权访问的产品实例分页列表。调用其他端点时，你可以使用返回的 ID 来筛选结果。
使用统计	该请求返回已认证客户端的产品实例按产品聚合的使用统计数据。

实例发现

GET /stats/v1/filters/instances

查询参数

参数	说明	类型
products[]	按产品筛选。接受的值： HB （无头浏览器）， DC （数据中心代理）， null （所有产品）。	字符串数组
page	页码。默认值： 1.	整数
per_page	每页结果数。默认值： 100。最大值： 100.	整数

请求示例

要开始筛选数据，你首先需要识别你的特定资源。以下示例展示了如何列出你可用的数据中心代理 (DC) 和 无头浏览器 (HB) 实例。

输入示例

GET /stats/v1/filters/instances?products[]=HB&products[]=DC&page=1&per_page=50
Authorization: Bearer {YOUR_API_KEY}

输出示例

{
  "data": [
    {
      "uuid": "my-hb-instance-uuid",
      "name": "my-hb-instance",
      "status": "enabled",
      "product": "HB"
    },
    {
      "uuid": "my-dc-instance-uuid",
      "name": "my-dc-instance",
      "status": "disabled",
      "product": "DC"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 2,
      "total_pages": 1
    }
  }
}

响应字段

字段	说明	类型
uuid	实例的唯一标识符。	字符串（UUID）
name	在仪表板中配置的实例名称。	字符串
status	产品实例状态（例如， enabled 或 disabled).	字符串
product	产品标识符（例如， HB （无头浏览器）， DC （数据中心代理）等）。	字符串
page	当前页码。	整数
per_page	此页的结果数量。	整数
total_items	所有页面中匹配记录的总数。	整数
total_pages	总页数。始终至少为 1，即使没有结果也是如此。	整数

使用统计

GET /stats/v1/usage

重要： 单个请求允许的最大日期范围（即 date_to 和 date_from之间的差值）为 31 天。如需获取更长时间段的使用数据，请按 31 天一批执行查询。

查询参数

参数	说明	类型
product	产品标识符（例如， HB （无头浏览器）， DC （数据中心代理）等）	字符串
date_to	开始日期，包含当日（例如，UTC YYYY-MM-DDTHH:mm:ssZ 或带时区偏移的 YYYY-MM-DDTHH:mm:ss+02:00).	日期（ISO 8601）
date_from	结束日期，包含当日。格式与 date_to.	日期（ISO 8601）
group_by	结果分组选项。接受的值： DAY, TARGET, INSTANCE。可以组合多个值。值的顺序决定了数据分组的顺序。	字符串数组
instances[]	将结果筛选到特定实例。接受多个从以下位置获取的 UUID： GET /stats/v1/filters/instances。无效或无法识别的 UUID 将被忽略。	UUID（字符串数组）
page	页码。默认值： 1.	整数
per_page	每页结果数。默认值： 100。最大值： 100.	整数

- 必填参数

请求示例

1. 按 TARGET 分组

以下示例展示了如何通过按目标分组来获取 无头浏览器 (HB) 的使用指标，以查看所选日期范围内每个目标的总请求数和流量。

输入示例

GET /stats/v1/usage?product=HB&date_from=2025-11-01T00:00:00Z&date_to=2025-11-30T23:59:59Z&group_by[]=TARGET
Authorization: Bearer {YOUR_API_KEY}

输出示例

{
  "data": [
    {"grouped_by": ["some.target.A"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["some.target.B"], "requests": 10, "traffic_bytes": 100}
  ],
  "totals": {
    "requests": 20,
    "traffic_bytes": 200
  },
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 100,
      "total_pages": 2
    },
    "grouping": ["TARGET"]
  }

2. 按 DAY + TARGET 分组

本示例展示了如何按HB) 的使用情况同时根据 日期 和 目标 进行拆分，以便查看每个目标在每天消耗了多少流量。

输入示例

GET /stats/v1/usage?product=HB&date_from=2025-11-01T00:00:00Z&date_to=2025-11-30T23:59:59Z&group_by[]=DAY&group_by[]=TARGET
Authorization: Bearer {YOUR_API_KEY}

输出示例

  "data": [
    {"grouped_by": ["2025-11-01", "some.target.A"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["2025-11-01", "some.target.B"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["2025-11-02", "some.target.A"], "requests": 10, "traffic_bytes": 100},
    {"grouped_by": ["2025-11-02", "some.target.B"], "requests": 10, "traffic_bytes": 100}
  ],
  "totals": {
    "requests": 40,
    "traffic_bytes": 400
  },
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total_items": 200,
      "total_pages": 4
    },
    "grouping": ["DAY", "TARGET"]
  }
}

响应字段

字段	说明	类型
grouped_by	分组选项，顺序与请求的 group_by 参数	字符串数组
data.requests	分组后的时间段/维度组合的总请求数。	整数
data.traffic_bytes	分组后的时间段/维度组合的总流量（字节）。	整数
totals	所选时间段的总聚合值。	对象
totals.requests	整个所选时间段内的总请求数。	整数
totals.traffic_bytes	整个所选时间段内的总流量（字节）。	整数
page	当前页码。	整数
per_page	此页的结果数量。	整数
total_items	所有页面中匹配记录的总数。	整数
total_pages	总页数。始终至少为 1，即使没有结果也是如此。	整数
meta.grouping	当前启用的分组选项，其顺序与它们在 grouped_by中出现的顺序一致。映射 group_by 请求参数。	字符串数组

速率限制

为确保稳定性，仪表板API 的速率限制会针对所有请求按 API 密钥和客户端账户应用。

• 10 每个 API 密钥的请求数

• 100 单个客户端所有 API 密钥的总请求数

错误处理

以下是你在使用仪表板API 时可能遇到的一些常见错误类型：

错误代码	错误消息	说明
400	错误请求	请求无法被理解。请检查请求格式是否正确。
401	无效请求	用户输入了无效的 API 密钥。
403	禁止访问	访问被拒绝：缺少 API 密钥。请联系支持团队或你的客户经理。
429	请求过多	用户已达到线程/并发会话限制。
500	服务器内部错误	服务器发生了意外问题。请稍后重试。

如有问题、访问问题或集成支持需求，请联系 [e-mail] 或你的客户经理。报告问题时，请包含：

• 所使用的端点和查询参数

• 返回的 HTTP 状态码

• 完整响应体（分享前请隐藏你的 API 密钥）

• 失败请求的时间戳（建议使用 UTC）