> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/documentation/cn/kong-zhi-tai/dashboard-api.md).

# 控制台 API

该 **仪表盘 API** 使您能够 **访问您的产品使用统计数据** 以编程方式访问，并将指标集成到您的内部系统中。这使您无需使用网页上的 Oxylabs 仪表盘即可进行自动报告和实时使用监控。

{% hint style="info" %}
**注意：** Dashboard API 目前支持 **数据中心代理 (DC**) 和 **无头浏览器 (HB)**。您还可以跟踪 [**住宅代理**](/products/cn/proxies/residential-proxies/public-api.md), [**移动代理**](/products/cn/proxies/mobile-proxies/public-api.md), [**网页解锁器**](/products/cn/web-unblocker/usage-statistics.md)，以及 [**网页爬虫API**](/products/cn/web-scraper-api/usage-and-billing/usage-statistics.md) 的使用统计数据，只需简单的 API 请求。
{% endhint %}

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

```
https://api.oxylabs.io/
```

## 身份验证

{% hint style="warning" %}
**重要：** 如需获取您的 Dashboard API 密钥，请联系我们的 [**客户支持**](mailto:support@oxylabs.io) 团队。提交请求后，密钥将在一个工作日内生成并直接提供给您。
{% endhint %}

您必须将密钥包含在每个请求的 `Authorization` 标头中，并使用 `Bearer` 方案。

```
Authorization: Bearer {YOUR_API_KEY}
```

## 端点

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

<table><thead><tr><th width="236.8125">端点</th><th>描述</th></tr></thead><tbody><tr><td><a href="#instance-discovery">实例发现</a></td><td>该请求返回您账户有权访问的产品实例分页列表。您可以使用返回的 ID 在调用其他端点时筛选结果。</td></tr><tr><td><a href="#usage-statistics">使用统计</a></td><td>该请求返回已认证客户端的产品实例按产品汇总的使用统计数据。</td></tr></tbody></table>

### 实例发现

```
GET /stats/v1/filters/instances
```

#### 查询参数

<table><thead><tr><th width="166">参数</th><th width="268.0481770833333">描述</th><th>类型</th></tr></thead><tbody><tr><td><code>products[]</code></td><td>按产品筛选。可接受的值： <code>HB</code> （无头浏览器）， <code>DC</code> （数据中心代理）， <code>null</code> （所有产品）。</td><td>字符串数组</td></tr><tr><td><code>page</code></td><td>页码。默认值： <code>1</code>.</td><td>整数</td></tr><tr><td><code>per_page</code></td><td>每页结果数。默认值： <code>100</code>。最大值： <code>100</code>.</td><td>整数</td></tr></tbody></table>

#### 示例请求

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

**输入示例**

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

**输出示例**

```json
{
  "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
    }
  }
}
```

#### 响应字段

<table><thead><tr><th width="166">字段</th><th width="268.0481770833333">描述</th><th>类型</th></tr></thead><tbody><tr><td><code>uuid</code></td><td>该实例的唯一标识符。</td><td>字符串 (UUID)</td></tr><tr><td><code>name</code></td><td>在仪表盘中配置的实例名称。</td><td>字符串</td></tr><tr><td><code>status</code></td><td>产品实例状态（例如， <code>已启用</code> 或 <code>已禁用</code>).</td><td>字符串</td></tr><tr><td><code>product</code></td><td>产品标识符（例如， <code>HB</code> （无头浏览器）， <code>DC</code> （数据中心代理）等）。</td><td>字符串</td></tr><tr><td><code>page</code></td><td>当前页码。</td><td>整数</td></tr><tr><td><code>per_page</code></td><td>此页的结果数。</td><td>整数</td></tr><tr><td><code>total_items</code></td><td>所有页面中匹配记录总数。</td><td>整数</td></tr><tr><td><code>total_pages</code></td><td>总页数。始终至少为 <code>1</code>，即使没有结果。</td><td>整数</td></tr></tbody></table>

### 使用统计

```
GET /stats/v1/usage
```

{% hint style="warning" %}
**重要：** 单次请求的最大日期范围（两者之间的差值 `date_to` 和 `date_from`) 为 **31 天**。要检索更长时间段的使用数据，请按 31 天为批次执行查询。
{% endhint %}

#### 查询参数

<table><thead><tr><th width="166">参数</th><th width="268.0481770833333">描述</th><th>类型</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><code>product</code></mark></td><td>产品标识符（例如， <code>HB</code> （无头浏览器）， <code>DC</code> （数据中心代理）等）</td><td>字符串</td></tr><tr><td><mark style="background-color:green;"><code>date_to</code></mark></td><td>开始日期，包含当日（例如，UTC <code>YYYY-MM-DDTHH:mm:ssZ</code> 或支持时区偏移 <code>YYYY-MM-DDTHH:mm:ss+02:00</code>).</td><td>日期（ISO 8601）</td></tr><tr><td><mark style="background-color:green;"><code>date_from</code></mark></td><td>结束日期，包含当日。格式与 <code>date_to</code>.</td><td>日期（ISO 8601）</td></tr><tr><td><mark style="background-color:green;"><code>group_by</code></mark></td><td>结果分组选项。可接受的值： <code>DAY</code>, <code>TARGET</code>, <code>INSTANCE</code>。可组合多个值。值的顺序决定数据分组的顺序。</td><td>字符串数组</td></tr><tr><td><code>instances[]</code></td><td>将结果筛选为特定实例。接受从 <code>GET /stats/v1/filters/instances</code>获取的多个 UUID。无效或无法识别的 UUID 将被忽略。</td><td>UUID（字符串数组）</td></tr><tr><td><code>page</code></td><td>页码。默认值： <code>1</code>.</td><td>整数</td></tr><tr><td><code>per_page</code></td><td>每页结果数。默认值： <code>100</code>。最大值： <code>100</code>.</td><td>整数</td></tr></tbody></table>

\- 必填参数

#### 示例请求

**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}
```

**输出示例**

```json
{
  "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}
```

**输出示例**

```json

  "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"]
  }
}
```

#### 响应字段

<table><thead><tr><th width="190">字段</th><th width="344.0481770833333">描述</th><th>类型</th></tr></thead><tbody><tr><td><code>grouped_by</code></td><td>与请求的 <code>group_by</code> 参数相同顺序的分组选项。</td><td>字符串数组</td></tr><tr><td><code>data.requests</code></td><td>该分组的时间段/维度组合的总请求数。</td><td>整数</td></tr><tr><td><code>data.traffic_bytes</code></td><td>该分组的时间段/维度组合的总流量（字节）。</td><td>整数</td></tr><tr><td><code>totals</code></td><td>所选时间段的总汇总值。</td><td>对象</td></tr><tr><td><code>totals.requests</code></td><td>整个所选时间段内的总请求数。</td><td>整数</td></tr><tr><td><code>totals.traffic_bytes</code></td><td>整个所选时间段内的总流量（字节）。</td><td>整数</td></tr><tr><td><code>page</code></td><td>当前页码。</td><td>整数</td></tr><tr><td><code>per_page</code></td><td>此页的结果数。</td><td>整数</td></tr><tr><td><code>total_items</code></td><td>所有页面中匹配记录总数。</td><td>整数</td></tr><tr><td><code>total_pages</code></td><td>总页数。始终至少为 <code>1</code>，即使没有结果。</td><td>整数</td></tr><tr><td><code>meta.grouping</code></td><td>按其在中出现顺序排列的当前分组选项 <code>grouped_by</code>。与 <code>group_by</code> 请求参数一致。</td><td>字符串数组</td></tr></tbody></table>

## 速率限制

为确保稳定性，Dashboard API 的速率限制会针对所有请求按每个 API key 和每个客户端账户应用。

* `10` 每个 API key 的请求数
* `100` 单个客户端的所有 API key 的请求数

## 错误处理

以下是使用 Dashboard API 时可能遇到的一些常见错误类型：

<table><thead><tr><th width="166">错误代码</th><th width="268.0481770833333">错误信息</th><th>描述</th></tr></thead><tbody><tr><td><code>400</code></td><td>错误请求</td><td>无法理解该请求。请检查请求格式是否正确。</td></tr><tr><td><code>401</code></td><td>无效请求</td><td>用户输入了无效的 API key。</td></tr><tr><td><code>403</code></td><td>禁止访问</td><td>访问被拒绝：缺少 API key。请联系支持团队或您的客户经理。</td></tr><tr><td><code>429</code></td><td>请求过多</td><td>用户已达到线程/并发会话限制。</td></tr><tr><td><code>500</code></td><td>内部服务器错误</td><td>服务器出现了意外问题。请稍后再试。</td></tr></tbody></table>

如有问题、访问问题或集成支持需求，请联系 [**support@oxylabs.io**](mailto:support@oxylabs.io) 或您的客户经理。报告问题时，请包含：

* 所使用的端点和查询参数
* 返回的 HTTP 状态码
* 完整响应正文（分享前请遮盖您的 API key）
* 失败请求的时间戳（优先使用 UTC）


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/documentation/cn/kong-zhi-tai/dashboard-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.