list_competitor_ads
Browse a watched competitor’s captured ads: copy, CTA, format, activity dates, landing/snapshot URLs, and durable mirrored media URLs — fetch them to SEE the creatives. Combine with the ads server’s list_creative_library (your own creatives) to compare messaging and angles.
The library is a cached snapshot refreshed roughly weekly by watch pulls; this call never triggers a new fetch (see the freshness block). The competitor must already be watched — use list_watched_competitors first, or watch_competitor to add one.
Parameters#
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
competitor | string | yes | The watched competitor’s name or domain ("acme.com") | |
platform | string | no | Filter — meta or google (meta_ads/google_ads accepted as aliases; unknown values → validation_error) | |
limit | integer | no | 24 | Max ads to return (max 48) |
offset | integer | no | 0 | Pagination offset |
Returns#
{
"advertiser": { "id": 42, "name": "Acme Corp", "domain": "acme.com" },
"ads": [
{
"id": 981,
"platform": "meta",
"advertiser_name": "Acme Corp",
"advertiser_domain": "acme.com",
"format": "image",
"is_active": true,
"deactivated_at": null,
"started_on": "2026-06-02",
"last_shown_on": "2026-07-08",
"last_pulled_at": "2026-07-10T04:12:00+00:00",
"landing_url": "https://acme.com/summer",
"snapshot_url": "https://www.facebook.com/ads/library/?id=123",
"variant_count": 3,
"variants": [
{
"position": 0,
"title": "Summer sale",
"body": "20% off everything…",
"cta_text": "Shop Now",
"cta_type": "SHOP_NOW",
"image_url": "https://…durable-mirror…/981.jpg",
"video_url": null,
"link_url": "https://acme.com/summer"
}
]
}
],
"total": 37,
"offset": 0,
"limit": 24,
"has_more": true,
"freshness": {
"last_pulled_at": "2026-07-10T04:12:00+00:00",
"note": "Cached ad-library snapshot, refreshed ~weekly by watch pulls; this call never triggers a new fetch."
},
"source": "adlyse.brand_watch@v1"
}variants[].image_url prefers the durable mirrored copy over the vendor’s expiring CDN link. is_active and the activity dates are frozen at pull time — treat them as approximate, not live. snapshot_url links to the ad on the platform’s public library.
Errors#
error_type | When |
|---|---|
auth_error | Missing / invalid API key |
not_found | The competitor doesn’t match exactly one active watch (unknown or ambiguous — retry with the domain) |
validation_error | Unknown platform value |