`meta_ads_list_competitor_ads`

List Competitor Ads

Description

List a competitor's ads from the scraped Meta Ad Library corpus — real creative content (copy, CTA, landing URL, media metadata), not just snapshot links. Filter by active_only (still running), display_format (image, video, carousel, text), first_seen_since / first_seen_until (when the ad first appeared — the platform's start date, else when Hopkin first scraped it; use these for "new ads" and read count), since (last seen by a scrape on/after a date, so long-running ads match too), and search (full-text over ad copy). Requires no Meta connection — the corpus is maintained by Hopkin's daily scrape of tracked advertisers. Get advertiser IDs from meta_ads_list_tracked_competitors or meta_ads_track_competitor. Each ad leaves out raw_data, the raw scraped payload behind these fields, unless include_raw is set. ${META_CARDS_NOTE} raw_data is large, so pair include_raw with a small limit.

Read-onlyIdempotent

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "meta_ads_list_competitor_ads",
    "arguments": {
      "advertiser_id": "adv-uuid-from-tracked-list",
      "reason": "Review a competitor’s current creative strategy"
    }
  }
}

hopkin meta competitor-ads list

Flag	Type	Required	Description
`--advertiser-id`	`string`	Required	The advertiser ID from meta_ads_list_tracked_competitors or meta_ads_track_competitor
`--active-only`	`boolean`	Optional	Only ads still running (no stopped_running_at)
`--display-format`	`string`	Optional	Filter by creative format as Meta labels it (case-insensitive). Observed values: image, video, carousel, multi_images, dco, dpa. dco and dpa are Meta's dynamic formats (dynamic creative and catalog/advantage+ ads) and are the most common in the corpus.
`--since`	`string`	Optional	Only ads a scrape last saw on or after this ISO date/timestamp (e.g. 2026-07-01) — compares last_seen_at, so an ad running for months still matches. For ads that are NEW, use first_seen_since.
`--first-seen-since`	`string`	Optional	Only ads that first appeared on or after this ISO date/timestamp (e.g. 2026-10-05). "First appeared" is the platform's own start date (started_running_at) when the ad has one, else first_seen_at — when Hopkin first scraped it, so a newly tracked advertiser's older ads can count as new. For "new ads in the last 7 days", pass the date 7 days ago with limit: 1 and read count.
`--first-seen-until`	`string`	Optional	Only ads that first appeared on or before this ISO date/timestamp — same clock as first_seen_since. A date alone (e.g. 2026-10-11) includes that whole UTC day.
`--search`	`string`	Optional	Case-insensitive search over ad copy (primary text, headline, description), up to 100 characters
`--limit`	`integer`	Optional	Number of ads per page (default: 20, max: 100)
`--cursor`	`string`	Optional	Pagination cursor from previous response
`--include-raw`	`boolean`	Optional	Also return raw_data, the scraped Meta Ad Library payload behind the normalized fields. Off by default. A carousel or dynamic (dco, dpa) ad's real copy is per card: its normalized headline and primary_text hold only the ad-level copy, often a catalog template such as '{{product.name}}'. Such ads carry `cards`, one per card in order, with its title, body, link_url, cta_text (plus caption and link_description when present) and an image and/or video link: our mirror, or the card's own Meta CDN URL marked short_lived (it expires) when not mirrored yet. include_raw adds only the full scraped payload behind them. Raw rows are large (~9.7 KB per ad on average and up to 268 KB), so pass a small `limit` (e.g. 3-5) when setting this.

{
  "mcpServers": {
    "meta-ads": {
      "url": "https://meta.mcp.hopkin.ai",
      "transport": "sse"
    }
  }
}

Parameters

Name	Type	Required	Description
`advertiser_id`	`string`	Required	The advertiser ID from meta_ads_list_tracked_competitors or meta_ads_track_competitorminLength: 1
`reason`	`string`	Required	Why this tool call is neededminLength: 1, maxLength: 500

Optional parameters (9)

Name	Type	Required	Description
`active_only`	`boolean`	Optional	Only ads still running (no stopped_running_at)
`display_format`	`string`	Optional	Filter by creative format as Meta labels it (case-insensitive). Observed values: image, video, carousel, multi_images, dco, dpa. dco and dpa are Meta's dynamic formats (dynamic creative and catalog/advantage+ ads) and are the most common in the corpus.minLength: 1
`since`	`string`	Optional	Only ads a scrape last saw on or after this ISO date/timestamp (e.g. 2026-07-01) — compares last_seen_at, so an ad running for months still matches. For ads that are NEW, use first_seen_since.pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z\|[+-]\d{2}:\d{2})?)?$
`first_seen_since`	`string`	Optional	Only ads that first appeared on or after this ISO date/timestamp (e.g. 2026-10-05). "First appeared" is the platform's own start date (started_running_at) when the ad has one, else first_seen_at — when Hopkin first scraped it, so a newly tracked advertiser's older ads can count as new. For "new ads in the last 7 days", pass the date 7 days ago with limit: 1 and read count.pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z\|[+-]\d{2}:\d{2})?)?$
`first_seen_until`	`string`	Optional	Only ads that first appeared on or before this ISO date/timestamp — same clock as first_seen_since. A date alone (e.g. 2026-10-11) includes that whole UTC day.pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z\|[+-]\d{2}:\d{2})?)?$
`search`	`string`	Optional	Case-insensitive search over ad copy (primary text, headline, description), up to 100 charactersminLength: 1, maxLength: 100
`limit`	`integer`	Optional	Number of ads per page (default: 20, max: 100)min: 1, max: 100
`cursor`	`string`	Optional	Pagination cursor from previous responseminLength: 1
`include_raw`	`boolean`	Optional	Also return raw_data, the scraped Meta Ad Library payload behind the normalized fields. Off by default. A carousel or dynamic (dco, dpa) ad's real copy is per card: its normalized headline and primary_text hold only the ad-level copy, often a catalog template such as '{{product.name}}'. Such ads carry `cards`, one per card in order, with its title, body, link_url, cta_text (plus caption and link_description when present) and an image and/or video link: our mirror, or the card's own Meta CDN URL marked short_lived (it expires) when not mirrored yet. include_raw adds only the full scraped payload behind them. Raw rows are large (~9.7 KB per ad on average and up to 268 KB), so pass a small `limit` (e.g. 3-5) when setting this.

Examples

Browse all ads

{
  "advertiser_id": "adv-uuid-from-tracked-list",
  "reason": "Review a competitor’s current creative strategy"
}

hopkin meta competitor-ads list --advertiser-id adv-uuid-from-tracked-list

Active video ads

{
  "advertiser_id": "adv-uuid-from-tracked-list",
  "active_only": true,
  "display_format": "video",
  "reason": "Study competitor video creative"
}

hopkin meta competitor-ads list --advertiser-id adv-uuid-from-tracked-list --active-only true --display-format video

New ads this month

{
  "advertiser_id": "adv-uuid-from-tracked-list",
  "first_seen_since": "2026-08-01",
  "reason": "Find newly launched competitor ads"
}

hopkin meta competitor-ads list --advertiser-id adv-uuid-from-tracked-list --first-seen-since 2026-08-01

Search ad copy

{
  "advertiser_id": "adv-uuid-from-tracked-list",
  "search": "free shipping",
  "reason": "Find offer-led competitor messaging"
}

hopkin meta competitor-ads list --advertiser-id adv-uuid-from-tracked-list --search free shipping