前言¶
在 B 站三连推广里做投放，后台能看报表，但一旦要按账户、计划、单元或创意做批量核对，或把日/小时数据接到自己的脚本和 Agent 流程里，手工导出往往跟不上。Marketing API（MAPI）侧有自定义报表接口，但维度名、指标名、旧版结构与创意驱动 2.0 两套口径不能混用，日期范围也要按天循环请求。下面介绍 SkillHub 上的 B站三连广告-报表，它把 POST /open_api/report/v3/custom/query 的用法、约束和错误处理写进 Agent 可执行的 SKILL 说明，并与同系列的授权主流程 Skill 衔接。
这是什么¶
B站三连广告-报表（包内标识 bilibili-sanlian-ads-reporting）面向 Bilibili 三连广告 MAPI 的投放报表场景：通过自定义报表端点查询消耗、曝光、点击、转化等投放指标，支持按账户、计划、单元、创意（旧结构）或项目、媒体（创意驱动投放 2.0）等维度聚合，粒度可选日期或小时。
Skill 托管在 SkillHub（用户 user_b0010d5c），分类为 data-analysis；公开页显示评分 93403、下载约 2492 次（数据取自 Skill 线索，以 SkillHub 页面为准）。当前资源快照版本为 3.0.4，约 7 个文件、107.4 KB，更新时间为 2026-10-12。
同系列中，创编与列表类接口不返回花费、曝光、点击；投放效果数据应走本 Skill 所描述的报表端点。账户余额、预算、资金流水属于 bilibili-sanlian-ads-account-finance，与报表消耗不是同一套数据，字段级也无法一一对账。
核心功能¶
经与 Skill 说明核对，能力集中在单一报表端点及其查询规则上。
自定义报表查询¶
核心请求为：
POST https://cm.bilibili.com/takumi/api/open_api/report/v3/custom/query
Authorization: Bearer {access_token}
Content-Type: application/json
X-Call-Source: sanlian-skills
X-Sanlian-Skills-Version: 3.0.4
请求体中选定维度（dimensions）、指标（metrics）、起止时间，并可加 filters 过滤。完整维度与指标列表以 Skill 内 references/807_自定义报表.md（对应开发者文档「投放报表 / 自定义报表」，doc_id 807）为准；名称必须为文档中的精确字符串，未知指标会直接被拒。
账户级与对象级口径¶
- 账户汇总：只传
account_id，不附加计划/单元/创意/项目/媒体维度或过滤。一次账户级查询可同时覆盖旧版投放与创意驱动 2.0 投放的汇总。 - 对象级：在
dimensions或filters[].field中出现对象 ID 时，会进入「旧版模式」或「创意驱动 2.0 模式」之一，两套指标表不同。
| 旧版模式 | 创意驱动 2.0 模式 | |
|---|---|---|
| 触发条件 | campaign_id、unit_id 或 creative_id 出现在维度或过滤字段 |
promotion_id 或 media_id 出现在维度或过滤字段 |
| 指标集 | 旧版指标集 | 116 个基础指标 |
| 衍生指标 | 支持 | 不支持（无 cost_per_*、*_rate、*_roi 等，需用绝对值自行计算） |
两套维度不能混查；混用会返回「系统繁忙」，应拆成两次请求。指标不在当前模式列表中会返回「指标 [xxx] 不存在」，属参数错误，不宜当作瞬时故障重试。
时间、过滤与返回行含义¶
- 单日请求：
start_time与end_time必须为同一天，格式YYYY-MM-DD。跨多天区间需在 Agent 或脚本中按天顺序循环，一天完成并校验后再发下一天，不要并行扇出。 - 过滤：每个 filter 的
values最多 100 个 ID，且 filter 存在时values不能为空；更大 ID 集需拆分多次请求。 - 粒度：可选按日或按小时；按小时会显著增加行数，需配合分页策略。
- 无花费无行：接口只返回有消耗的 row；缺行表示当日该对象无消耗，不是漏数，也无需为此重试。
金额字段¶
- 无后缀字段单位为元（展示用）。
- 带
_milli后缀为毫分位原值（1 元 = 100000），对账、计费核对建议用整数运算处理_milli字段。
Agent 侧调用约定¶
Skill 要求所有 MAPI 调用经封装脚本执行，而不是手写 curl / requests / fetch，且不要跨账户或对象并行请求：
# Unix / macOS / Linux
scripts/mapi.sh call [--query-file q.json] [--body-file body.json]
# Windows
py -3 scripts/mapi_client.py call [--query-file q.json] [--body-file body.json]
脚本负责加载与刷新 token、附加请求头、限速（Rule 1）及统一错误分类。业务成败以响应体为准，不能只看 HTTP 状态码。
中文触发词包括：报表、数据、消耗、花费、曝光、点击、转化、投放数据、自定义报表、看数据、跑量情况。对话里出现「昨天」「最近」「跑得好」等表述时，Skill 要求先解析为明确时区、日期、指标与对象范围，再发起请求。
安装与启用¶
SkillHub 官方地址：
https://api.skillhub.cn/user_b0010d5c/sanlian-ads-reporting
当前环境对该 URL 的页面抓取未成功（HTTP 405），具体「安装」按钮或 CLI 命令请以 SkillHub 站内说明为准。Skill 遵循通用 SKILL.md 格式，安装后由支持 Skills 的客户端（如 Cursor、Claude Code 等）加载；各客户端启用路径若与 SkillHub 文档不一致，以你使用的客户端与 SkillHub 当前指引为准。
前置依赖（Skill 内硬性要求）：
- 有效的 MAPI
access_token与广告主account_id。缺任一项时，应先使用同系列bilibili-sanlian-ads（B站三连广告-授权与主流程）完成 OAuth、刷新 token 并确认账户范围。 - 调用报表前阅读
references/807_自定义报表.md拼请求体。 - 遵守主 Skill 中的顺序调用与出错即停原则；长区间先估算「按天 / 按页」调用计划再执行。
Skill 页注明可能涉及第三方服务或模型，需按介绍配置相应 API Key（若你的部署路径需要）。
典型用法¶
下面是与官方 Skill 说明一致的可复现流程，不代替真实 token 与 account_id。
查昨日账户总消耗¶
- 通过
bilibili-sanlian-ads确认access_token与account_id。 - 在
body.json中设置账户级查询：仅account_id，start_time与end_time均为目标自然日（例如2026-10-19），选定文档中的消耗、曝光、点击、转化类指标名。 - 执行：
scripts/mapi.sh call --body-file body.json
- 解析响应体中的业务状态与数据行；若需多日，将日期改为下一天并等待上一日响应校验完成后再发。
按计划看投放表现（旧版结构）¶
- 在
dimensions或filters中使用campaign_id（或unit_id/creative_id），进入旧版指标集。 - 指标名仅从旧版列表选取；需要点击率、转化成本等衍生指标时，在旧版模式下使用接口提供的衍生字段（2.0 模式需自行用基础指标计算）。
- 单日、单页顺序查询；filter 中计划 ID 超过 100 个时拆批。
创意驱动 2.0（项目 / 媒体）¶
- 维度或过滤使用
promotion_id或media_id，勿与campaign_id等旧版字段同请求。 - 仅请求 116 个基础指标；ROI、率类需本地计算。
- 与旧版计划数据对比时，分别拉两套报表，不要期望一次请求合并。
与资金类问题的区分¶
用户问「花了多少钱 / 效果怎样」→ 本 Skill。问「账户余额、预算、流水」→ 转 bilibili-sanlian-ads-account-finance。
适用场景与注意¶
适合：
- 已接入或计划接入 B 站三连 MAPI，需要在 Agent 对话中用自然语言拉自定义报表的团队。
- 需要按日或按小时核对消耗、曝光、点击、转化，且愿意遵守「按天顺序、不并行扇出」的调用纪律的自动化脚本维护者。
- 同时使用旧版计划/单元/创意与创意驱动 2.0，需要 Skill 明确两套维度与指标边界的情况。
注意：
- 须先具备 MAPI 授权与 App 凭证；平台对 MAPI 接入有商务与权限门槛，需向 B 站侧申请 Appkey / Appsecret 及报表拉取权限。
- 不要猜测指标英文名，也不要从其他广告平台直译指标名。
- 查询失败时，先检查：起止日期是否同一天且格式正确、指标是否属于当前模式、维度是否混用；勿通过反复替换维度/指标「试 API」。
- 报表消耗与财务账户数据系统不同，对账时需区分数据源。
结尾¶
B站三连广告-报表把三连 MAPI 自定义报表的端点、双投放结构、按日循环与金额精度写进可执行的 Skill 规则，并与授权主流程、财务 Skill 分工清晰，适合把「看数据、看消耗、看跑量」交给 Agent 时作为专用能力加载。
官方地址：https://api.skillhub.cn/user_b0010d5c/sanlian-ads-reporting
