API 可读取的数据

API 读取的数据与您在 Gloriads 中看到的完全相同，而且从不更改您的账户或广告。

端点

每个参数和每个字段都列在 API 参考文档中，并提供 Try it 按钮。

周期

/summary、/timeline 和 /reports/products 覆盖一个周期。以下两种方式，只发送一种：

• 两者都不发送时，默认为 last_30_days，与仪表盘相同。
• range 只覆盖完整的天，也就是仪表盘汇总的那些天：last_30_days 是截至昨天的 30 天，this_month 和 this_year 也截至昨天。亚马逊会在点击发生几天后才把销售归因到该点击，所以今天的数据永远不完整。
• today 就是今天；每月 1 日的 this_month 也是今天（当月还没有完整的天）。
• all_time 从 Gloriads 保存的最早一天开始，一直到今天，与仪表盘上的全部时间相同。
• 要包含今天，请发送 start_date 和 end_date，并把 end_date 设为今天。
• timezone（Asia/Shanghai、Europe/Paris、America/New_York……）决定“今天”是哪一天，默认为 UTC。
• 每个返回结果都会在 period 中注明它覆盖的日期。

对比两个周期

在 /summary、/timeline 或 /reports/products 中加上 compare，与仪表盘上的对比相同：

返回结果会增加一个 comparison，包含对比周期的数据，并给出花费、销售额、ACOS、展示量、点击次数、CPC 和购买次数各自的变化：

"changes": {
  "spend": { "kind": "change", "percent": 18.2, "direction": "up", "tone": "neutral" },
  "acos": { "kind": "change", "percent": -6.5, "direction": "down", "tone": "good" }
}

• 两个周期都截至昨天，与仪表盘相同：日期范围包含今天时会去掉今天，period 会注明这一点。
• kind: "new" 表示该数据之前为零；kind: "none" 表示没有可对比的内容（没有销售时的 ACOS）。
• tone 表示变化是否是好消息，与仪表盘上的颜色一致。花费始终为 neutral。
• all_time 之前没有更早的周期，today 没有完整的天：此时 comparison 会在 unavailable 中说明原因。
• 如果 Gloriads 没有对比周期的历史数据，该周期的数据为 null，history_covered 为 false。

筛选

API 拒绝未知的值，返回 400 并指出是哪个值，而不是返回全为零的结果。

周期总计

curl "https://gloriads.com/api/v1/summary?range=last_month&marketplaces=US" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "period": { "start_date": "2026-09-01", "end_date": "2026-09-30", "range": "last_month", "timezone": "UTC" },
  "currency": "USD",
  "spend": 13140.53,
  "sales": 46562.2,
  "acos": 28.22,
  "roas": 3.54,
  "impressions": 3945723,
  "clicks": 13973,
  "ctr": 0.35,
  "average_cpc": 0.94,
  "purchases": 1479,
  "conversion_rate": 10.58,
  "by_marketplace": [ … ],
  "by_ad_product": [ … ],
  "meta": { "data_last_date": "2026-10-09", "history_covered": true, "truncated": false }
}

• acos、ctr 和 conversion_rate 是百分比：28.22 表示 28.22%。
• purchases 统计的是订单数，与广告后台的购买次数（Purchases）一致，不是件数。
• 缺少基数的比率（没有销售时的 ACOS）为 null，绝不为 0。

按天或按月

/timeline 使用相同的周期和筛选参数，在 data 中按天或按月各返回一个数据点。

• granularity=auto（默认）在 92 天以内按天，超过则按月，与仪表盘的图表相同。
• 周期超过 92 天时，API 拒绝 granularity=day。
• 没有任何数据的日期不会出现在结果中。

按商品

/reports/products 为每个推广的商品（ASIN）返回一行，按 sort（默认 spend）和 order（默认 desc）排序。

• product_id: null 汇总了亚马逊没有关联到任何商品的数据，主要来自品牌推广。
• title 是亚马逊商品报告给出的商品名称，取该商品在此期间花费最多的站点上的名称。product_id: null 的行为 null；在 Gloriads 尚未从亚马逊收到该账户的商品名称之前，也为 null。
• 结果分页返回：请参阅限制与错误。

流媒体电视广告

与仪表盘一样，其他报告都不包含流媒体电视广告（在 Prime Video 和各类流媒体应用中播放的电视广告）：它们所依据的亚马逊报告里没有这类广告。/reports/streaming-tv 从亚马逊的另一份报告中读取它，每次只读取一个站点。

curl "https://gloriads.com/api/v1/reports/streaming-tv?marketplace_id=3478512345678901&range=last_30_days" \
  -H "Authorization: Bearer YOUR_API_KEY"

• 周期最长 31 天，且须在最近 95 天之内：这是亚马逊对该报告的限制。
• 某个周期的首次请求可能返回 "status": "pending"，表示亚马逊正在生成报告，通常需要几分钟。请等待 meta.retry_after_seconds 秒后再次请求。报告生成后会保留 3 小时。
• 每个广告活动都附有花费、展示量、cpm（每千次展示成本）、点击次数、销售额、购买次数和 units_sold。
• 金额使用站点自己的币种，而不是美元。
• "status": "unavailable"：亚马逊不向该账户提供流媒体电视广告，例如 KDP 作者的账户。

广告活动和广告组

两者都需要 marketplace_id，即 /marketplaces 返回的某个 id。

curl "https://gloriads.com/api/v1/campaigns?marketplace_id=3478512345678901&states=ENABLED" \
  -H "Authorization: Bearer YOUR_API_KEY"

• 列出商品推广、品牌推广和展示广告中已启用和已暂停的广告活动。已归档的广告活动永远不会列出。
• 预算和竞价使用站点自己的币种（/marketplaces 中的 currency_code）。
• provenance 说明 Gloriads 是创建了该广告活动、修改过它，还是从未动过它。
• /ad-groups?campaign_id=… 只返回某个广告活动的广告组。
• 每页最多 1,000 行（默认 100 行）。

关键词、投放目标和广告

/targets 和 /ads 列出某一个广告活动内部的内容。两者都需要 marketplace_id 和 campaign_id；ad_group_id 只保留其中一个广告组。

curl "https://gloriads.com/api/v1/targets?marketplace_id=3478512345678901&campaign_id=28430987654321" \
  -H "Authorization: Bearer YOUR_API_KEY"

• /targets 列出每个关键词及其 match_type（EXACT、PHRASE、BROAD），以及商品投放（ASIN）、品类、自动投放组、否定关键词和否定投放，附各自的 bid 和状态。bid: null 表示使用广告组的默认竞价。
• /ads 列出每个广告及其推广的商品（product_ids）。
• 它们在您请求的那一刻从亚马逊读取，不包含任何效果数据。
• 涵盖商品推广、品牌推广和展示广告。已归档的投放目标和广告永远不会列出。
• 每页最多 1,000 行（默认 100 行）。

规则和操作日志

• /rules 列出所有规则，最近编辑的排在前面。
• /rules/{rule_id}/runs 显示最近每次运行检查了什么、更改了什么。规则测试（立即测试）不会列出。
• /activity 列出 Gloriads 在亚马逊上执行的每项操作：创建或复制的广告活动、添加的商品、规则做出的变更、撤销。规则的一次运行在每个站点各出现一次，rule_run_id 相同。tool=rule 只保留规则的操作。
• /activity/{operation_id} 读取单项操作：轮询它，即可跟进仍在运行的操作。
• /activity/{operation_id}/lines 逐行列出该操作做了什么：涉及的广告活动、广告组、广告或投放目标，是创建、更改还是归档，每个值修改前后的内容，以及某一行失败时亚马逊返回的错误。每页最多 500 行：一次规则运行可能多达 5,000 行。

数据的更新频率

• 它们就是仪表盘上的数据：读取相同的数据，用相同的代码计算。
• 广告效果的金额以美元计。 亚马逊会把各站点的数据换算为美元。
• 亚马逊在点击发生几天后才归因销售，所以周期最后几天的数据还会增长一段时间。meta.data_last_date 说明数据截至哪一天。
• 每个站点的广告活动最多每 30 分钟从亚马逊读取一次。 meta.synced_at 说明读取时间。首次请求某个站点时，列表可能为空，并带有 meta.syncing: true：请一分钟后再请求。
• 商品数据每天更新一次。 如果周期的开始日期早于 Gloriads 保存的历史数据，返回结果会带有 meta.history_covered: false。
• 关键词、投放目标和广告每次请求时都从亚马逊实时读取：meta.read_at 说明读取时间。
• 流媒体电视广告的数据在亚马逊生成报告后保留 3 小时：meta.report_ready_at 说明报告的生成时间。