> 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-mian-ban/dashboard-api.md).

# 控制面板 API

通过 Dashboard API 以编程方式访问 Oxylabs 产品用户，跟踪使用统计。

该 **Dashboard API** 允许你 **访问你的产品使用统计** 以编程方式并将指标集成到你的内部系统中。这允许在不使用网页上的 Oxylabs 仪表板的情况下进行自动化报告和实时使用监控。

{% hint style="info" %}
**注意：** Dashboard API 目前支持 **数据中心代理（DC**）和 **Agent Browser（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> （Agent Browser）， <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）和 Agent Browser（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>enabled</code> 或 <code>disabled</code>).</td><td>字符串</td></tr><tr><td><code>product</code></td><td>产品标识符（例如， <code>HB</code> （Agent Browser）， <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> （Agent Browser）， <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 分组**

下面的示例展示如何获取 Agent Browser（`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 分组**

下面的示例展示如何拆分 Agent Browser（`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 密钥和按客户端账户应用于所有请求。

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

## 错误处理

以下是使用 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 密钥。</td></tr><tr><td><code>403</code></td><td>禁止访问</td><td>访问被拒绝：缺少 API 密钥。请联系支持团队或你的客户经理。</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 密钥）
* 失败请求的时间戳（优先使用 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.