ScrapeUnblocker Documentation

The Meta Ad Library plugin turns any Facebook/Instagram advertiser’s public ads into structured JSON. Give it an advertiser - a Page name or a numeric Page ID - and it returns the ads Meta shows in its Ad Library: each with the ad copy, call-to-action, format, the image and video creative URLs, the landing page, the platforms it runs on, and its run dates. It runs a real browser on our own anti-bot fleet and reads the same Ad Library a person sees, then captures Meta’s internal results directly - so you get an advertiser’s whole active set without a Meta developer account, an access token, or the political-ads-only limits of Meta’s official Ad Library API. This is a competitor-ads tool: see what your competitors are running, in which format, and where they send the click.

Try it in the dashboard first: app.scrapeunblocker.com/dashboard/plugins. You get a live results view plus a copy-paste snippet.

Endpoint

POST /ads/meta-ad-library

Field	Required	Notes
`advertiser`	yes	A Facebook Page name (keyword search) or a numeric Page ID (that advertiser’s whole set). A Page ID is the exact-advertiser match; a name can span several Pages sharing it.
`country`	no	Ad Library country (ISO-2, e.g. `US`, `GB`, `DE`). Meta scopes the library by country. Default `US`.
`active_status`	no	`active` (default), `inactive`, or `all`.
`media_type`	no	Creative filter: `all` (default), `image`, `video`, or `meme`.
`max_ads`	no	Upper bound on ads returned; the plugin paginates until it reaches this or runs out. Default `50`, max `500`.

curl -X POST "https://api.scrapeunblocker.com/ads/meta-ad-library?advertiser=Nike&country=US&active_status=active&max_ads=30" \
  -H "x-scrapeunblocker-key: YOUR_API_KEY"

Response

{
  "advertiser": "Nike",
  "resultsCollected": 30,
  "has_more": true,
  "results": [
    {
      "ad_archive_id": "1049210304776058",
      "collation_id": "1065726462591268",
      "page_id": "15087023444",
      "page_name": "Nike",
      "page_profile_uri": "https://www.facebook.com/nike/",
      "page_like_count": 39281044,
      "is_active": true,
      "started_running": "2026-08-07",
      "ended": null,
      "platforms": ["FACEBOOK", "INSTAGRAM", "MESSENGER", "THREADS"],
      "display_format": "VIDEO",
      "is_dynamic": false,
      "ad_text": "Made to move. The new season is here.",
      "title": "Shop the latest",
      "caption": "nike.com",
      "cta_text": "Shop now",
      "cta_type": "SHOP_NOW",
      "link_url": "https://www.nike.com/w/new-3n82y",
      "link_description": "Free shipping for members",
      "creatives": [
        {
          "type": "video",
          "image_url": "https://scontent.xx.fbcdn.net/v/preview.jpg",
          "video_url": "https://video.xx.fbcdn.net/v/hd.mp4"
        }
      ],
      "categories": ["UNKNOWN"],
      "currency": null,
      "reach_estimate": null
    }
  ]
}

Result fields

Field	Notes
`resultsCollected`	Number of ads returned on this call (deduplicated by `ad_archive_id`).
`has_more`	`true` when the advertiser has more ads than `max_ads` returned - raise `max_ads` for more.
`ad_archive_id`	Meta’s own Ad Library id for the ad.

Ad fields

Field	Notes
`page_name` / `page_id`	The advertiser’s Page name and id.
`page_profile_uri`	Link to the advertiser’s Facebook Page.
`is_active`	Whether the ad is currently running.
`started_running` / `ended`	Run dates (ISO `YYYY-MM-DD`, UTC). `ended` is `null` while the ad is still active.
`platforms`	Where the ad runs: `FACEBOOK`, `INSTAGRAM`, `MESSENGER`, `AUDIENCE_NETWORK`, `THREADS`.
`display_format`	Meta’s creative format: `IMAGE`, `VIDEO`, `DCO` (dynamic), `CAROUSEL`, `DPA`.
`is_dynamic`	`true` for dynamic-creative ads (DCO/DPA) whose copy is a catalog template. Meta fills placeholders like `{{product.name}}` per viewer from the advertiser’s product feed, so `ad_text`/`title` come back as the raw template - `is_dynamic` lets you flag those instead of treating the template as literal ad text.
`ad_text`	The primary ad copy. For dynamic (DCO) ads this can be a template like `{{product.brand}}` - that is the ad as Meta serves it (see `is_dynamic`).
`title` / `caption`	The headline and the display link/caption.
`cta_text` / `cta_type`	The button label (`Shop now`) and its type (`SHOP_NOW`, `LEARN_MORE`, `SIGN_UP`, …).
`link_url`	The landing page the ad sends the click to.
`creatives`	The ad’s media: an array of `{ type, image_url, video_url }`. `type` is `image` or `video`; a video also carries its `image_url` preview. Carousel/DCO ads return one entry per card.
`categories`	Meta’s ad categories, `["UNKNOWN"]` for ordinary commercial ads.

When an advertiser has no ads

An advertiser with no ads for the given filters is a valid answer, not an error - the call returns 200 with an empty results array and resultsCollected: 0. Widen active_status to all or drop the media_type filter to see more.

Errors

Status	Meaning
`400`	Invalid `country` / `active_status` / `media_type`.
`502`	Meta blocked the fetch or no ads could be collected (anti-bot or proxy failure) - retry.
`504`	The fetch timed out.

What you can build

Competitor ad monitoring - track exactly which ads a rival runs, in which format, and how often the creative changes.
Creative research - pull a brand’s video and image creative URLs to study hooks, offers and CTAs at scale.
Landing-page intel - link_url shows where every ad sends the click - which offers and pages a competitor pushes.
Format and platform mix - see whether a competitor leans on video vs. image, and Facebook vs. Instagram vs. Threads.
Market entry - scope who is advertising in a country before you spend.

Meta’s own Ad Library API

Meta publishes an Ad Library API, but through it the full data is limited to political and social-issue ads - ordinary commercial “competitor ads” are not returned. This plugin reads the same public Ad Library page anyone can open, so it covers commercial advertisers too, with your ScrapeUnblocker key and nothing else.

Get Started

No-code area

Spider Cloud

Plugins

AI Assistants

Guides

Code Examples

Meta Ad Library plugin

Endpoint

Response

Result fields

Ad fields

When an advertiser has no ads

Errors

What you can build

Meta’s own Ad Library API

Next steps

Open the plugins

Get an API key

​Endpoint

​Response

​Result fields

​Ad fields

​When an advertiser has no ads

​Errors

​What you can build

​Meta’s own Ad Library API

​Next steps

Open the plugins

Get an API key

Endpoint

Response

Result fields

Ad fields

When an advertiser has no ads

Errors

What you can build

Meta’s own Ad Library API

Next steps