# 流量与用量

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

## 端点

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

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

## 获取聚合流量

```bash
curl -H "Authorization: Bearer API_KEY" \
     "https://api.helodata.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-Helodata-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.helodata.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: 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://docs.helodata.com/helodata-zh/api-can-kao/traffic.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.