# 报表

Reports 提供定时或临时的账号数据导出——适合计费管线、周报推送、BI 工具接入。

## 端点

| 方法       | 路径                   | 用途              |
| -------- | -------------------- | --------------- |
| `GET`    | `/reports`           | 列出报表（定时 + 近期运行） |
| `POST`   | `/reports`           | 安排新报表           |
| `GET`    | `/reports/{id}`      | 获取报表定义          |
| `PATCH`  | `/reports/{id}`      | 更新计划、字段、目标      |
| `DELETE` | `/reports/{id}`      | 删除报表            |
| `POST`   | `/reports/{id}/run`  | 立即运行（返回运行 ID）   |
| `GET`    | `/reports/runs/{id}` | 获取运行状态与下载链接     |

## 安排定时

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name":   "weekly-traffic",
       "type":   "traffic",
       "filters": {
         "products": ["residential", "mobile"]
       },
       "schedule": "0 9 * * MON",
       "format":   "csv",
       "destination": {
         "type":  "email",
         "email": "ops@acme.com"
       }
     }' \
     https://api.helodata.com/v1/reports
```

### 报表类型

| `type`        | 内容                  |
| ------------- | ------------------- |
| `traffic`     | 按子账号 / 产品 / 天聚合带宽   |
| `requests`    | 请求日志采样              |
| `invoices`    | 发票条目                |
| `subusers`    | 子账号清单快照             |
| `isp_batches` | ISP 批次清单 + 每 IP 健康度 |

### 目标

| `type`    | 字段                                        |
| --------- | ----------------------------------------- |
| `email`   | `email`                                   |
| `webhook` | `url`、`signing_secret`                    |
| `s3`      | `bucket`、`prefix`、`role_arn`（跨账号写入用）      |
| `gcs`     | `bucket`、`prefix`、`service_account_email` |

### 计划表达式

`schedule` 接受标准 5 字段 cron，**UTC 时区**。也可省略 `schedule` 仅用于临时运行。

## 临时运行

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"from":"2026-05-01","to":"2026-05-28"}' \
     "https://api.helodata.com/v1/reports/rep_01HX2K3PQ4M5/run"
```

返回：

```json
{
  "run_id":  "run_01HX2K3PQ4M5",
  "status":  "queued"
}
```

轮询状态：

```bash
curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/reports/runs/run_01HX2K3PQ4M5
```

`status` 变为 `completed` 时响应含 `download_url`（签名，1 小时有效）——或报表已经推送到 `destination`。

## 格式

| `format`  | 说明                   |
| --------- | -------------------- |
| `csv`     | UTF-8 逗号分隔，含表头       |
| `tsv`     | UTF-8 制表符分隔          |
| `json`    | 换行分隔 JSON（NDJSON）    |
| `parquet` | 推送到 `s3` / `gcs` 时最佳 |

## 保留

报表运行与可下载产物保留 **90 天**。需要更长保留请推到 `s3` / `gcs`。

## 错误

| 状态码   | code                      | 含义                  |
| ----- | ------------------------- | ------------------- |
| `422` | `invalid_cron`            | cron 表达式不合法         |
| `422` | `destination_unreachable` | webhook URL 预检失败    |
| `403` | `feature_not_in_plan`     | Reports 仅 Pro+ 套餐可用 |


---

# 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/reports.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.