Meta Ad Library API

Search active and past ads by keyword or advertiser across countries, get creatives, copy, platforms and run dates, and EU transparency data of a single ad.

Overview and use cases on the Meta Ad Library API page; response format, pagination and errors are the same for every API (conventions).

GET/v1/ads/search5 credits / call

Ads matching a keyword or an advertiser page, with filters, up to 30 per call.

One of q or page_id is required.

ParameterInTypeDefaultDescription
qquerystring—Keyword (required unless page_id is set)
page_idquerystring—Only ads of this advertiser page
countryquerystringALLTwo-letter country code or ALL
statusqueryactive | inactive | allactiveAd status
ad_typequeryall | politicalallAll ads or political/issue ads
media_typequeryall | image | video | meme | noneallCreative type
platformsquerystring—Comma-separated: facebook, instagram, messenger, audience_network
languagesquerystring—Comma-separated ISO 639-1 codes
active_fromquerydate—Running on or after (YYYY-MM-DD)
active_toquerydate—Running on or before (YYYY-MM-DD)
matchqueryany | exactanyKeyword match
sortqueryrelevance | impressionsrelevanceOrder
limitqueryinteger (1–30)30Ads per page (max 30, one page of the source)
cursorquerystring—pagination.next_cursor of the previous page
curl "https://api.scrapecrate.com/v1/ads/search?q=running%20shoes" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "data": [
    {
      "id": "1234567890123456",
      "url": "https://www.facebook.com/ads/library/?id=1234567890123456",
      "page": {
        "id": "102030405060708",
        "name": "Example Shoes"
      },
      "status": "active",
      "started_at": "2026-10-15",
      "platforms": [
        "facebook",
        "instagram"
      ],
      "format": "image",
      "body": "Run further with our new trainers.",
      "title": "New collection",
      "link_url": "https://example.com/shoes",
      "cta": {
        "text": "Shop now",
        "type": "SHOP_NOW"
      },
      "images": [
        {
          "type": "image",
          "url": "https://example.com/creative.jpg"
        }
      ]
    }
  ],
  "pagination": {
    "next_cursor": "eyJwIjoyfQ",
    "has_more": true
  },
  "meta": {
    "request_id": "req_8f2c1a9b0d3e4f5a6b7c",
    "credits_used": 5,
    "credits_remaining": 9999
  }
}
GET/v1/ads/{ad_id}5 credits / call

One ad with creatives, payer and beneficiary, and EU/UK transparency data.

ParameterInTypeDefaultDescription
ad_id*pathstring—Ad Library ID
countryquerystringALLCountry used to look the ad up
curl "https://api.scrapecrate.com/v1/ads/1234567890123456" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "data": {
    "id": "1234567890123456",
    "page": {
      "id": "102030405060708",
      "name": "Example Shoes"
    },
    "status": "active",
    "started_at": "2026-10-15",
    "payers": [
      {
        "payer": "Example Shoes Ltd",
        "beneficiary": "Example Shoes Ltd"
      }
    ],
    "transparency": {
      "eu": {
        "reach": 120000,
        "age_min": 18,
        "age_max": 65
      }
    }
  },
  "meta": {
    "request_id": "req_8f2c1a9b0d3e4f5a6b7c",
    "credits_used": 5,
    "credits_remaining": 9999
  }
}
GET/v1/ads/pages/search5 credits / call

Advertiser pages whose ads match a keyword.

ParameterInTypeDefaultDescription
q*querystring—Keyword
countryquerystringALLTwo-letter country code or ALL
limitqueryinteger (1–10)10Pages (max 10, one page of the source)
curl "https://api.scrapecrate.com/v1/ads/pages/search?q=running%20shoes" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "data": [
    {
      "id": "102030405060708",
      "name": "Example Shoes",
      "category": "Shopping & retail",
      "like_count": 52000,
      "verified": true
    }
  ],
  "pagination": {
    "next_cursor": "eyJwIjoyfQ",
    "has_more": true
  },
  "meta": {
    "request_id": "req_8f2c1a9b0d3e4f5a6b7c",
    "credits_used": 5,
    "credits_remaining": 9999
  }
}

Get an advertiser

GET/v1/ads/pages/{page_id}5 credits / call

Advertiser page details with Instagram account and active ads estimate.

ParameterInTypeDefaultDescription
page_id*pathstring—Advertiser page ID
curl "https://api.scrapecrate.com/v1/ads/pages/102030405060708" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "data": {
    "id": "102030405060708",
    "name": "Example Shoes",
    "category": "Shopping & retail",
    "like_count": 52000,
    "instagram": {
      "username": "exampleshoes",
      "followers": 81000,
      "verified": false
    },
    "active_ads_estimate": 42
  },
  "meta": {
    "request_id": "req_8f2c1a9b0d3e4f5a6b7c",
    "credits_used": 5,
    "credits_remaining": 9999
  }
}

List an advertiser's ads

GET/v1/ads/pages/{page_id}/ads5 credits / call

The ads of one advertiser page, with the same filters as search.

ParameterInTypeDefaultDescription
page_id*pathstring—Advertiser page ID
countryquerystringALLTwo-letter country code or ALL
statusqueryactive | inactive | allactiveAd status
media_typequeryall | image | video | meme | noneallCreative type
limitqueryinteger (1–30)30Ads per page (max 30, one page of the source)
cursorquerystring—pagination.next_cursor of the previous page
curl "https://api.scrapecrate.com/v1/ads/pages/102030405060708/ads" \
  -H "X-API-Key: YOUR_API_KEY"
{
  "data": [
    {
      "id": "1234567890123456",
      "page": {
        "id": "102030405060708",
        "name": "Example Shoes"
      },
      "status": "active",
      "started_at": "2026-10-15",
      "platforms": [
        "facebook",
        "instagram"
      ],
      "format": "image",
      "body": "Run further with our new trainers."
    }
  ],
  "pagination": {
    "next_cursor": "eyJwIjoyfQ",
    "has_more": true
  },
  "meta": {
    "request_id": "req_8f2c1a9b0d3e4f5a6b7c",
    "credits_used": 5,
    "credits_remaining": 9999
  }
}