> For the complete documentation index, see [llms.txt](https://docs.ipdunar.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipdunar.com/zh/api-can-kao/traffic.md).

# 流量与用量

跨产品读取带宽与请求分析。每个产品形态一致——只换路径前缀。

## 端点

| 路径                     | 产品  |
| ---------------------- | --- |
| `/residential/traffic` | 住宅  |
| `/mobile/traffic`      | 移动  |
| `/isp/traffic`         | ISP |

| 路径                    | 用途           |
| --------------------- | ------------ |
| `/{product}/traffic`  | 聚合带宽         |
| `/{product}/requests` | 请求日志采样       |
| `/{product}/sessions` | 粘性会话清单（网关产品） |

## 获取聚合流量

```bash
curl -H "Authorization: Bearer API_KEY" \
     "https://api.ipdunar.com/v1/residential/traffic?from=2026-05-01&to=2026-05-28&group_by=subuser"
```

### 查询参数

| 参数         | 必填 | 说明                                          |
| ---------- | -- | ------------------------------------------- |
| `from`     | 是  | RFC 3339 起点                                 |
| `to`       | 是  | RFC 3339 终点（不含）                             |
| `group_by` | 否  | `subuser`、`region`、`asn`、`tag`、`day`、`hour` |
| `subuser`  | 否  | 限定单个子账号                                     |
| `region`   | 否  | 限定单个 ISO 国家代码                               |
| `tag`      | 否  | 限定单个 `X-Ipdunar-Tag` 值                      |

### 响应

```json
{
  "from": "2026-05-01T00:00:00Z",
  "to":   "2026-05-28T00:00:00Z",
  "rows": [
    {
      "subuser":   "sub_01HX2K3PQ4M5",
      "bytes_in":  12345678,
      "bytes_out": 9876543,
      "requests":  4210,
      "errors":    51,
      "error_rate": 0.012
    }
  ]
}
```

ISP 增加按 IP 维度；移动增加 `asn` 和 `carrier_name`：

```json
{ "ip": "198.51.100.42", "bytes_in": 1234567, "bytes_out": 9876543, "requests": 4210 }
{ "asn": 6167, "carrier_name": "Verizon Wireless", "bytes_in": 222345 }
```

## 采样请求日志

```bash
curl -H "Authorization: Bearer API_KEY" \
     "https://api.ipdunar.com/v1/residential/requests?subuser=sub_01HX2K3PQ4M5&limit=100"
```

返回最近 48 小时最多 1,000 条采样请求：

```json
{
  "data": [
    {
      "request_id":  "req_01HX2K3PQ4M5",
      "ts":          "2026-05-28T07:14:22Z",
      "subuser":     "sub_01HX2K3PQ4M5",
      "method":      "GET",
      "target_host": "example.com",
      "status":      200,
      "bytes":       38745,
      "exit_ip":     "198.51.100.42",
      "exit_geo":    "us/ca/la",
      "exit_asn":    7922,
      "tag":         "campaign-acme-q2"
    }
  ]
}
```

用于发现热点目标与调试单次调用，**不用于计费**——这是采样，非全量。

## 粒度

数据分辨率随时间降采样：

| 时长      | 分辨率  |
| ------- | ---- |
| < 24 小时 | 1 分钟 |
| 1–14 天  | 5 分钟 |
| 14–90 天 | 1 小时 |
| > 90 天  | 1 天  |

如需细粒度历史数据，请在保留窗口内尽早拉取。

## 错误

| 状态码   | code               | 含义                 |
| ----- | ------------------ | ------------------ |
| `422` | `range_too_wide`   | `from..to` 超过 90 天 |
| `422` | `invalid_group_by` | `group_by` 取值未知    |

```
```


---

# 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://docs.ipdunar.com/zh/api-can-kao/traffic.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.
