APIMUX DocsMeta Ad Library API
Search and retrieve Meta (Facebook/Instagram) ad library data
Search Ads
Search the Meta Ad Library with multi-dimensional filtering by keyword, advertiser, country, ad type, media type, and more.
- Endpoint:
GET /ads/searchorPOST /ads/search
Pagination Note: When paginating through multiple pages, next_page_token may exceed 8KB, causing URL length errors (HTTP 413/414). In this case, switch to POST and send parameters in the JSON request body.
Parameters
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
query | Query/Body | string | No | Search keyword. For exact match, wrap in double quotes, e.g. "nike air". |
page_id | Query/Body | string | No | Advertiser's Facebook page ID. Combined with query, filters within that page. |
country | Query/Body | string | No | Country code. Default ALL. e.g. CN, US. |
content_languages | Query/Body | string | No | Content language filter, comma-separated. e.g. zh,en. |
ad_type | Query/Body | string | No | Ad type. Default all. Options: all, political_and_issue_ads, housing_ads, employment_ads, credit_ads. |
active_status | Query/Body | string | No | Ad status. Default active. Options: active, inactive, all. |
media_type | Query/Body | string | No | Media type. Default all. Options: all, video, image, meme, image_and_meme, none. |
platforms | Query/Body | string | No | Platforms, comma-separated. Options: facebook, instagram, audience_network, messenger, threads. |
start_date | Query/Body | string | No | Start date (inclusive), format YYYY-MM-DD. |
end_date | Query/Body | string | No | End date (inclusive), format YYYY-MM-DD. |
sort_by | Query/Body | string | No | Sort order. Default impressions_high_to_low. Options: most_recent, impressions_high_to_low. |
next_page_token | Query/Body | string | No | Pagination token from previous response's pagination.next_page_token. |
Request Example
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'Get Ad Details
Get detailed information for an ad by its unique ID.
- Endpoint:
GET /ads/detail
Parameters
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
ad_id | Query | string | Yes | Ad unique ID from the search endpoint response. |
Request Example
curl --request GET \
--url 'https://api.apimux.io/v1/ads/detail?ad_id=1234567890' \
--header 'Authorization: Bearer YOUR_API_KEY'Response Example
Note: The current response structure is identical to a single ad element in the search results. Future versions may include additional detail fields.
{
"code": 200,
"message": "success",
"data": {
"ad_id": "1234567890",
"page_id": "100000000000001",
"page_name": "Example Page",
"ad_creative_id": "200000000000002",
"ad_creative_body": "This is the ad copy content...",
"ad_creative_link_caption": "example.com",
"ad_creative_link_title": "Ad link title",
"ad_creative_link_description": "Ad 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": []
}
}