报表

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

端点

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

安排定时

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": "[e-mail]"
       }
     }' \
     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 仅用于临时运行。

临时运行

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"

返回：

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

轮询状态：

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+ 套餐可用