洞察端点
广告 API 在四个层级上提供相同的报告封装
GET /ad_account/insightsGET /campaigns/{campaign_id}/insightsGET /ad_groups/{ad_group_id}/insightsGET /ads/{ad_id}/insights
使用与您想要获取结果的范围相匹配的端点。每个端点都返回相同的顶层响应格式，其中包含适用于该范围的 ID 和元数据。
| 参数 | 类型 | 必需 | 备注 |
|---|---|---|---|
time_granularity（时间粒度） | string | 否 | 聚合桶大小：daily（每日）或 none（无）。 |
aggregation_level（聚合级别） | string | 否 | 聚合范围：ad_account（广告账户）、campaign（系列）、ad_group（广告组）或 ad（广告）。 |
limit | 整数 | 否 | 介于 1 和 10000 之间。 |
before | string | 否 | 上一页的游标。 |
after | string | 否 | 下一页的游标。 |
time_ranges（时间范围） | 字符串数组 | 否 | 针对时间范围的过滤器。 |
filters（过滤器） | 字符串数组 | 否 | 一个或多个过滤表达式。 |
fields（字段） | 字符串数组 | 否 | 每行中需要投射的字段。 |
sort（排序） | 字符串数组 | 否 | 排序表达式。 |
示例
这些示例使用“点击量”作为表现最佳广告的排名指标。如果其他支持的指标更符合您的绩效衡量方式，您可以按该指标进行排序。
系列中表现最佳广告的每日洞察
首先，找出整个时间窗口内表现最佳的广告。
curl -sS -G "https://api.ads.openai.com/v1/campaigns/cmpn_101/insights" \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
--data-urlencode 'time_granularity=none' \
--data-urlencode 'aggregation_level=ad' \
--data-urlencode 'limit=1' \
--data-urlencode 'fields[]=ad_id' \
--data-urlencode 'fields[]=ad_name' \
--data-urlencode 'fields[]=clicks' \
--data-urlencode 'fields[]=impressions' \
--data-urlencode 'time_ranges[]={"type":"date_range","since":"2026-04-25","until":"2026-05-01"}' \
--data-urlencode 'sort[]={"field":"clicks","direction":"desc"}'然后使用返回的 ad_id 获取该广告的每日表现。
curl -sS -G "https://api.ads.openai.com/v1/ads/$AD_ID/insights" \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
--data-urlencode 'time_granularity=daily' \
--data-urlencode 'fields[]=readable_time' \
--data-urlencode 'fields[]=clicks' \
--data-urlencode 'fields[]=impressions' \
--data-urlencode 'fields[]=ctr' \
--data-urlencode 'time_ranges[]={"type":"date_range","since":"2026-04-25","until":"2026-05-01"}'项目中表现最佳的广告
使用广告账户端点对整个项目中的广告进行排名。
curl -sS -G "https://api.ads.openai.com/v1/ad_account/insights" \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
--data-urlencode 'time_granularity=none' \
--data-urlencode 'aggregation_level=ad' \
--data-urlencode 'limit=1' \
--data-urlencode 'fields[]=ad_id' \
--data-urlencode 'fields[]=ad_name' \
--data-urlencode 'fields[]=campaign_name' \
--data-urlencode 'fields[]=clicks' \
--data-urlencode 'fields[]=impressions' \
--data-urlencode 'time_ranges[]={"type":"date_range","since":"2026-04-25","until":"2026-05-01"}' \
--data-urlencode 'sort[]={"field":"clicks","direction":"desc"}'广告系列过去 7 天的每日表现
使用七天的 date_range 和每日粒度来获取每天一行的数据。
curl -sS -G "https://api.ads.openai.com/v1/campaigns/cmpn_101/insights" \
-H "Authorization: Bearer $OPENAI_ADS_API_KEY" \
--data-urlencode 'time_granularity=daily' \
--data-urlencode 'fields[]=readable_time' \
--data-urlencode 'fields[]=clicks' \
--data-urlencode 'fields[]=impressions' \
--data-urlencode 'fields[]=spend' \
--data-urlencode 'time_ranges[]={"type":"date_range","since":"2026-04-25","until":"2026-05-01"}'每个洞察行均包含 id、start_time 和 end_time，还可以包含派生的桶字段（如 readable_time 和 timezone）、投放指标（如 impressions、clicks、spend、ctr、cpc 和 cpm）以及资源元数据（如 campaign_name、ad_group_name 和 ad_name）。