> 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 产品用户进行程序化访问，以跟踪使用统计数据。

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

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

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

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

## 身份验证

{% hint style="warning" %}
**重要：** 如需获取您的 Dashboard API key，请联系我们的 [**客户支持**](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 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 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.
