用途
该技能用于从 Spotify Ads API 拉取广告报表数据，涵盖聚合指标、受众洞察以及异步 CSV 报表三类需求。它读取当前平台设置文件中的配置，并通过统一的请求封装脚本调用 API。
主要能力
aggregate（默认操作）
获取聚合的广告系列指标。可指定：
- entity_type：CAMPAIGN、AD_SET、AD、AD_ACCOUNT
- fields：指标字段，参数名为 fields（不是 report_fields）。建议字段包括 IMPRESSIONS、SPEND、CLICKS、REACH、FREQUENCY、COMPLETES；完整列表还包括 LISTENERS、NEW_LISTENERS、STREAMS、COMPLETION_RATE、STARTS、FIRST_QUARTILES、MIDPOINTS、THIRD_QUARTILES、VIDEO_VIEWS、CTR、OFF_SPOTIFY_IMPRESSIONS。
- granularity：HOUR、DAY、LIFETIME（默认 LIFETIME）
- report_start / report_end：ISO 8601 格式，DAY/HOUR 必填，LIFETIME 不发送
- entity_ids + entity_ids_type：可选，用于筛选特定 ID
- include_parent_entity：可选布尔值，为 AD_SET/AD 包含父级信息
校验规则：limit 为 1-50；entity_type 必须精确匹配；有 entity_ids 时必须带 entity_ids_type；有 statuses 时必须带 entity_status_type 且与状态归属匹配；聚合报表不使用 segments、dimensions、groupBy 或异步报表指标名；LIFETIME 不发送 report_start/report_end；DAY 使用 UTC 午夜时间戳；不要猜测转化指标名，有效字段包括 PAGE_VIEWS、LEADS、ADD_TO_CART、PURCHASES、REVENUE、RETURN_ON_AD_SPEND、AVERAGE_ORDER_VALUE、START_CHECKOUT、SIGN_UPS。
粒度约束：LIFETIME 不发送日期；DAY 日期范围须在 90 天内且为 UTC 午夜；HOUR 日期范围须在最近两周内。
totals
获取跨多个广告系列、广告组或广告的去重聚合指标，触达与频次在所有指定实体间去重。需要 entity_type（CAMPAIGN、AD_SET 或 AD，不支持 AD_ACCOUNT）、entity_ids（最多 50 个）、granularity（LIFETIME 或 DAY，不支持 HOUR）、fields（IMPRESSIONS、CLICKS、CTR、REACH、FREQUENCY），DAY 时需 report_start/report_end。
insights
获取受众洞察拆分。需要 insight_dimension（ACT_AND_SET、AGE、AUDIENCE、CITY、COUNTRY、FORMAT、GENDER、GENRE、INTERESTS、METRO、PLACEMENT、PLATFORM、PODCAST_EPISODE_TOPIC、REGION 或 TONE）、fields、entity_ids（一次仅一个广告组或广告系列 ID）、entity_ids_type（AD_SET 或 CAMPAIGN）。洞察报表不支持 E_CPCL、FREQUENCY、OFF_SPOTIFY_IMPRESSIONS、PAID_LISTENS_FREQUENCY、SKIPS、SPEND、STARTS、UNMUTES 等指标。洞察报表仅支持 LIFETIME，不发送 entity_type、report_start、report_end、granularity 或 limit。地理拆分映射：country -> COUNTRY，region/state -> REGION，metro/DMA -> METRO，city -> CITY。
当返回 HTTP 422 且错误码为 ILLEGAL.INSIGHT_REPORT.INSUFFICIENT_IMPRESSIONS、INSUFFICIENT_REACH 或 INSUFFICIENT_LISTENERS 时，表示实体数据不足，应告知用户尚未达到最低数据阈值，建议稍后再查（每天最多轮询一次）；若广告投放已结束，约在结束日期两周后停止重试。
async-create
创建异步 CSV 报表。需要 name（2-120 字符，仅字母数字、下划线、连字符）、granularity（DAY 或 LIFETIME）、dimensions（实体元数据列，如 AD_ACCOUNT_NAME、CAMPAIGN_NAME、CAMPAIGN_STATUS、CAMPAIGN_OBJECTIVE、AD_SET_NAME、AD_SET_STATUS、AD_SET_BUDGET、AD_SET_COST_MODEL、AD_NAME）、metrics（如 IMPRESSIONS_ON_SPOTIFY、IMPRESSIONS_OFF_SPOTIFY、SPEND、CLICKS、REACH、FREQUENCY、LISTENERS、NEW_LISTENERS、STREAMS、AD_COMPLETES、CTR、CPM、COMPLETION_RATE）、report_start（DAY 时必填）、report_end（可选）、campaign_ids（可选）、statuses（可选，默认 [ACTIVE]）、insight_dimension（可选，仅 LIFETIME 支持）。异步报表的 dimensions 仅限实体元数据列，地理、年龄、性别、平台、设备等应使用 insight_dimension 配合 LIFETIME，或使用 insight_reports。请求字段使用 dimensions 和 metrics，而非 groupBy、fields、dateRange 或 entityType。
async-status <report_id>
查询异步报表状态，完成后返回下载 URL。若处理中则报告状态并建议稍后再查；若 FAILED 则告知生成失败并建议用 async-create 重新创建。
使用方式
设置插件根目录并定义请求封装：
PLUGIN_ROOT="${CODEX_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.}}" api() { "$PLUGIN_ROOT/scripts/api-request.sh" report "$@"; }
首次调用 Ads API v3 前，阅读并遵循 $PLUGIN_ROOT/skills/api-reference/references/live-openapi.md。
获取设置值（TOKEN、AD_ACCOUNT_ID、AUTO_EXECUTE、BASE_URL、SDK_HEADER、SKILL_HEADER、PLUGIN_VERSION）可运行 api --env，输出可安全 eval，例如 eval $(api --env)。
执行行为：若 auto_execute 为 true 则直接执行；若为 false 则展示 curl 命令并请求确认。报表数据尽量以可读表格呈现；结果集较大时汇总关键指标并提供查看完整数据的选项。
适用场景
适用于需要从 Spotify Ads API 获取广告投放效果数据、受众画像拆分或导出 CSV 报表的广告运营与分析场景。
限制
- 聚合报表 limit 为 1-50。
- totals 最多 50 个实体 ID，不支持 HOUR 粒度与 AD_ACCOUNT。
- insights 一次仅支持一个实体 ID，仅 LIFETIME。
- 异步报表 dimensions 仅限实体元数据列。
- 洞察数据需达到最低展示、触达或听众阈值后才可用。
- 具体收费、价格、平台支持范围等资料暂未提供。