APIMUX文档Meta 广告库 API
Meta（Facebook/Instagram）广告库搜索与广告详情查询
搜索广告
在 Meta 广告库中搜索广告，支持按关键词、广告主、国家、广告类型、媒体类型等多维度筛选。
- 接口路径：
GET /ads/search或POST /ads/search
分页注意事项： 当进行多页翻页时，next_page_token 的长度可能超过 8KB，导致 URL 超长报错（HTTP 413/414）。在此情况下，请改用 POST 方法，将参数放入请求体（JSON 格式）中发送。
请求参数
| 参数名 | 位置 | 类型 | 是否必须 | 描述 |
|---|---|---|---|---|
query | Query/Body | string | 否 | 搜索关键词。如需精确匹配，请用英文双引号包裹，例如 "nike air"。 |
page_id | Query/Body | string | 否 | 广告主 Facebook 主页的唯一 ID。与 query 同时使用时，将在该主页范围内过滤关键词。 |
country | Query/Body | string | 否 | 国家/地区代码，默认为 ALL（全部）。例如：CN（中国）、US（美国）。 |
content_languages | Query/Body | string | 否 | 内容语言过滤，多个语言用逗号分隔，例如 zh,en。 |
ad_type | Query/Body | string | 否 | 广告类型，默认为 all。可选值：all、political_and_issue_ads、housing_ads、employment_ads、credit_ads。 |
active_status | Query/Body | string | 否 | 广告状态，默认为 active。可选值：active（投放中）、inactive（已停止）、all（全部）。 |
media_type | Query/Body | string | 否 | 媒体类型，默认为 all。可选值：all、video、image、meme、image_and_meme、none。 |
platforms | Query/Body | string | 否 | 广告投放平台，多个平台用逗号分隔。可选值：facebook、instagram、audience_network、messenger、threads。 |
start_date | Query/Body | string | 否 | 广告投放开始日期（含），格式 YYYY-MM-DD。 |
end_date | Query/Body | string | 否 | 广告投放结束日期（含），格式 YYYY-MM-DD。 |
sort_by | Query/Body | string | 否 | 排序方式，默认为 impressions_high_to_low（曝光量从高到低）。可选值：most_recent（最新）、impressions_high_to_low。 |
next_page_token | Query/Body | string | 否 | 翻页 Token，从上一次响应的 pagination.next_page_token 字段中获取。 |
请求示例
curl --request GET \
--url 'https://api.apimux.io/v1/ads/search?query=nike&country=US&active_status=active&media_type=video' \
--header 'Authorization: Bearer YOUR_API_KEY'获取广告详情
根据广告的唯一 ID 获取其详细信息。
- 接口路径：
GET /ads/detail
请求参数
| 参数名 | 位置 | 类型 | 是否必须 | 描述 |
|---|---|---|---|---|
ad_id | Query | string | 是 | 广告的唯一 ID，可从广告搜索接口的响应中获取。 |
请求示例
curl --request GET \
--url 'https://api.apimux.io/v1/ads/detail?ad_id=1234567890' \
--header 'Authorization: Bearer YOUR_API_KEY'响应示例
注意：当前此接口返回的结构与搜索结果列表中的单个广告元素结构完全一致。未来版本可能会补充更多详情字段。
{
"code": 200,
"message": "success",
"data": {
"ad_id": "1234567890",
"page_id": "100000000000001",
"page_name": "Example Page",
"ad_creative_id": "200000000000002",
"ad_creative_body": "这是广告文案内容...",
"ad_creative_link_caption": "example.com",
"ad_creative_link_title": "广告链接标题",
"ad_creative_link_description": "广告链接描述",
"impressions": {
"lower_bound": "10K",
"upper_bound": "15K"
},
"spend": {
"lower_bound": "100",
"upper_bound": "200",
"currency": "USD"
},
"start_date": "2026-02-15",
"end_date": "2026-03-05",
"ad_delivery_status": "ACTIVE",
"publisher_platforms": ["facebook", "instagram"],
"demographic_distribution": [
{
"percentage": "0.45",
"age": "25-34",
"gender": "male"
}
],
"region_distribution": [
{
"percentage": "0.6",
"region": "California"
}
],
"bylines": "Sponsored",
"estimated_audience_size": {
"lower_bound": "1000000",
"upper_bound": "1500000"
},
"ad_snapshot_url": "https://www.facebook.com/ads/archive/render_ad/?id=1234567890&access_token=...",
"videos": [
{
"thumbnail_url": "https://cdn.example.com/thumbnail.jpg",
"video_hd_url": "https://cdn.example.com/video.mp4"
}
],
"images": []
}
}