# 仪表盘 API

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

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

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

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

## 身份验证

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

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

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

## 端点

仪表板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}
```

**输出示例**&#x20;

```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> （无头浏览器）， <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>将结果筛选到特定实例。接受多个从以下位置获取的 UUID： <code>GET /stats/v1/filters/instances</code>。无效或无法识别的 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>

&#x20;     \- 必填参数

#### 请求示例

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

**输出示例**&#x20;

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

**输出示例**&#x20;

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

## 速率限制

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

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

## 错误处理

以下是你在使用仪表板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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.