SocialScrape
Get early access
Docs menu

Get started

Guides

API reference

Resources

Facebook Ad Library search (POST body)

Beta POST /v1/facebook/ad-library/search

POST /v1/facebook/ad-library/search

The same as the GET form, with the parameters in a JSON body.

  • Cost: 1 credit
  • Status: Beta. Built and tested against recorded responses; the shape may still gain fields.
  • Cache: Results are kept up to 30 days; send max_age_days to reuse them for free.
  • Timeout: A request still running after about 25 seconds answers 202 with a job to poll (Batch and jobs).

Parameters#

NameTypeRequiredDescriptionIn
querystringyesKeyword to search for. Also accepted as keyword, q.body
sortstringnoOrder of results: impressions is most impressions first (ScrapeCreators' default), newest is most recent. Changing it restarts the cursor chain. One of relevance, impressions, newest. Also accepted as sort_by, sortBy, order. Also accepted values: total_impressions for impressions, relevancy_monthly_grouped for newest.body
matchstringnoMatch any of the words, or the exact phrase. One of any_words, exact_phrase. Default any_words. Also accepted as search_type. Also accepted values: keyword_unordered for any_words, keyword_exact_phrase for exact_phrase.body
ad_typestringnoAll ads, or only political and issue ads. One of all, political. Default all. Also accepted values: political_and_issue_ads for political.body
languagestringnoOnly ads in this language, a 2-letter code (EN, ES, FR). Also accepted as lang.body
statusstringnoAd status. One of active, inactive, all. Default active. Also accepted as active_status. Also accepted values: ACTIVE for active, INACTIVE for inactive, ALL for all.body
media_typestringnoCreative type. meme is Meta's word for text on an image. One of all, image, video, meme, image_and_meme, none. Also accepted values: ALL for all, IMAGE for image, VIDEO for video, MEME for meme, IMAGE_AND_MEME for image_and_meme, NONE for none.body
start_datestringnoImpressions window start, YYYY-MM-DD.body
end_datestringnoImpressions window end, YYYY-MM-DD.body

Every request also accepts:

  • cursor: the cursor from the previous page (Pagination).
  • region: two-letter country code for results that vary by country. Changing it restarts the cursor chain.
  • trim: true for a smaller response without null fields and extra.
  • raw: true to also get the platform's original object as raw.
  • max_age_days: accept a cached result up to this many days old, for 0 credits (Caching).

Example request#

Set your key in the environment first (see Authentication).

curl
curl -X POST "https://api.socialscrape.io/v1/facebook/ad-library/search" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"nike"}'
Python
import os
import requests

payload = {
    "query": "nike",
}
res = requests.post(
    "https://api.socialscrape.io/v1/facebook/ad-library/search",
    headers={"x-api-key": os.environ["SOCIALSCRAPE_API_KEY"]},
    json=payload,
)
body = res.json()

if body["ok"]:
    print(body["data"])
else:
    print(body["error"]["code"], body["error"]["message"])
TypeScript
const res = await fetch("https://api.socialscrape.io/v1/facebook/ad-library/search", {
  method: "POST",
  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY!, "content-type": "application/json" },
  body: JSON.stringify({"query": "nike"}),
});
const body = await res.json();

if (body.ok) {
  console.log(body.data);
} else {
  console.error(body.error.code, body.error.message);
}

Example response#

This is a sample from a recorded response, lists and long text are shortened. Status 200.

{
  "ok": true,
  "credits_charged": 1,
  "credits_remaining": 4999,
  "cached": false,
  "cached_at": null,
  "request_id": "req_8e4b94c9048c2313d2aecdbe",
  "data": {
    "object": "list",
    "items": [
      {
        "object": "ad",
        "platform": "facebook",
        "id": "1550534860016399",
        "url": "https://www.facebook.com/ads/library/?id=1550534860016399",
        "advertiser": {
          "object": "advertiser",
          "platform": "facebook",
          "id": "115939511520844",
          "name": "Perfect themes",
          "url": "https://www.facebook.com/100093512920259/",
          "page_id": "115939511520844",
          "country": null,
          "verified": null,
          "ad_count": null,
          "extra": {
            "categories": [
              "Topic"
            ],
            "image_url": "https://scontent-dfw6-1.xx.fbcdn.net/v/t39.35426-6/701421303_1593266515068546_6584706353812290058_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=102&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=tv5rRAEs45MQ7kNvwGMz0Sw&_nc_oc=Ado7DqjLdVVkJoCgvbf9oZwyqtrHlC3CMQeiH6c...",
            "likes": 18599
          }
        },
        "status": "active",
        "started_at": "2026-05-19T07:00:00Z",
        "ended_at": null,
        "title": "๐•Š๐•ฆ๐•ก๐•–๐•ฃ ๐•™๐• ๐•ฅ ๐•จ๐•š๐••๐•˜๐•–๐•ฅ๐•ค ๐•’๐•ก๐•ก ๏ผ",
        "body": "๐Ÿ”ฅ๐ŸญThemepack is a FREE and personalized APP๐Ÿ˜ various styles of Theme๐Ÿ’Ž ใ€Weather๐Ÿ’–ใ€Photo๐Ÿ˜Šใ€Clockใ€Calendar to pick any widget to dress up your home screen๏ผ",
        "cta_text": "Install now",
        "landing_url": "http://play.google.com/store/apps/details?id=com.iconchanger.widget.theme.shortcut",
        "format": "image",
        "media": {
          "thumbnail_url": null,
          "video_url": null,
          "audio_url": null,
          "image_urls": [
            "https://scontent-dfw5-1.xx.fbcdn.net/v/t39.35426-6/700927950_933331229664450_6487763311056032772_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=iWNnbcABHX8Q7kNvwEsHUyv&_nc_oc=AdqYlI78KCc0tB1WeuueegWCBzYE9FoqEkSaEMUfj9zzSc-ivzPBV3bPOcO_pvZ..."
          ],
          "width": null,
          "height": null
        },
        "regions": null,
        "publisher_platforms": [
          "facebook",
          "instagram",
          "audience_network"
        ],
        "impressions": null,
        "spend": null,
        "extra": {
          "caption": "play.google.com",
          "categories": [
            "UNKNOWN"
          ],
          "contains_digital_created_media": false,
          "contains_sensitive_content": false,
          "gated_type": "ELIGIBLE",
          "hide_data_status": "NONE",
          "is_aaa_eligible": true,
          "media_expires_at": "2026-11-03T10:42:02Z",
          "regional_regulation_data": {
            "finserv": {
              "is_deemed_finserv": false,
              "is_limited_delivery": false
            },
            "tw_anti_scam": {
              "is_limited_delivery": false
            }
          }
        }
      },
      {
        "object": "ad",
        "platform": "facebook",
        "id": "962050096457659",
        "url": "https://www.facebook.com/ads/library/?id=962050096457659",
        "advertiser": {
          "object": "advertiser",
          "platform": "facebook",
          "id": "156405867784232",
          "name": "Depop",
          "url": "https://www.facebook.com/depop/",
          "page_id": "156405867784232",
          "country": null,
          "verified": null,
          "ad_count": null,
          "extra": {
            "categories": [
              "Shopping"
            ],
            "image_url": "https://scontent-dfw5-1.xx.fbcdn.net/v/t39.35426-6/706217505_1282327247074242_6940108535499458481_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=yTgOgRT-iNUQ7kNvwEAATlO&_nc_oc=Adqb9MR2Z3MzaEZWhdVMM6AOp3fsMofSRAZvw3T...",
            "likes": 98651
          }
        },
        "status": "active",
        "started_at": "2026-05-22T07:00:00Z",
        "ended_at": null,
        "title": "{{product.name}}",
        "body": "Free Depop Shipping just dropped. Go find something you love.",
        "cta_text": "Download",
        "landing_url": "http://itunes.apple.com/app/id518684914",
        "format": "dynamic_product",
        "media": {
          "thumbnail_url": null,
          "video_url": null,
          "audio_url": null,
          "image_urls": [
            "https://scontent-dfw5-1.xx.fbcdn.net/v/t39.35426-6/706277043_1509973367377594_8218495971134332071_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=74i6nzprYHoQ7kNvwGCryVF&_nc_oc=AdpKlVLIjbRmhK_AM1D5xuJizXN5zVzX1L3uA_BFc-EihsU_QpoLmC-deXDaYc...",
            "https://scontent-dfw5-1.xx.fbcdn.net/v/t39.35426-6/706198623_1758809891778866_1474232210027622534_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DHXTScSIgbsQ7kNvwFvztFE&_nc_oc=Adpn5ENw1NxU_RHg1aVqTzMzeCOg1lEZjUwRV7R073-XLo2ZbnLGIXJfTAZNxo...",
            "https://scontent-dfw6-1.xx.fbcdn.net/v/t39.35426-6/706277483_2044031086227797_898989708800947064_n.jpg?_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=vutTlfJHZoUQ7kNvwESGO8D&_nc_oc=AdoJGf4AO2p5f0Z0PZNcQHWQiU6NkFMS18_02RR6QMBj3mTwqW21xnYB2OiyrEQ..."
          ],
          "width": null,
          "height": null
        },
        "regions": null,
        "publisher_platforms": [
          "facebook",
          "instagram",
          "messenger"
        ],
        "impressions": null,
        "spend": null,
        "extra": {
          "caption": "itunes.apple.com",
          "cards": [
            {
              "body": "Free Depop Shipping just dropped. Go find something you love.",
              "cta_text": "Download",
              "image_url": "https://scontent-dfw5-1.xx.fbcdn.net/v/t39.35426-6/706277043_1509973367377594_8218495971134332071_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=74i6nzprYHoQ7kNvwGCryVF&_nc_oc=AdpKlVLIjbRmhK_AM1D5xuJizXN5zVzX1L3uA_BFc-EihsU_QpoLmC-deXDaYc...",
              "link_url": "https://www.depop.com/products/xaznbabyx-striped-wrap-blouse-purchased-to/",
              "title": "LOFT Women's Blouse"
            },
            {
              "body": "Free Depop Shipping just dropped. Go find something you love.",
              "cta_text": "Download",
              "image_url": "https://scontent-dfw5-1.xx.fbcdn.net/v/t39.35426-6/706198623_1758809891778866_1474232210027622534_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DHXTScSIgbsQ7kNvwFvztFE&_nc_oc=Adpn5ENw1NxU_RHg1aVqTzMzeCOg1lEZjUwRV7R073-XLo2ZbnLGIXJfTAZNxo...",
              "link_url": "https://www.depop.com/products/nwcollectibles-brand-new-with-tags-officially-214/",
              "title": "Nike Women's Jacket"
            },
            {
              "body": "Free Depop Shipping just dropped. Go find something you love.",
              "cta_text": "Download",
              "image_url": "https://scontent-dfw6-1.xx.fbcdn.net/v/t39.35426-6/706277483_2044031086227797_898989708800947064_n.jpg?_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=vutTlfJHZoUQ7kNvwESGO8D&_nc_oc=AdoJGf4AO2p5f0Z0PZNcQHWQiU6NkFMS18_02RR6QMBj3mTwqW21xnYB2OiyrEQ...",
              "link_url": "https://www.depop.com/products/xaznbabyx-v-neck-blouse-super-simple-but/",
              "title": "LOFT Women's Blouse"
            }
          ],
          "categories": [
            "UNKNOWN"
          ],
          "contains_digital_created_media": false,
          "contains_sensitive_content": false,
          "gated_type": "ELIGIBLE",
          "hide_data_status": "NONE",
          "is_aaa_eligible": false,
          "media_expires_at": "2026-11-03T12:31:10Z",
          "regional_regulation_data": {
            "finserv": {
              "is_deemed_finserv": false,
              "is_limited_delivery": false
            },
            "tw_anti_scam": {
              "is_limited_delivery": false
            }
          }
        }
      }
    ],
    "cursor": "eyJrIjoiZmJhZHMiLCJjIjoiQVFIVHR6TWN1R1ZGekcxSF85UzBpNjN5VTVMYjFzZHFDZmZaRjRYeHRHS205dXlVNG1BTUpkT2F3VEg1YUM4VWdvV2EifQ",
    "has_more": true,
    "parent": null
  },
  "cursor": "eyJrIjoiZmJhZHMiLCJjIjoiQVFIVHR6TWN1R1ZGekcxSF85UzBpNjN5VTVMYjFzZHFDZmZaRjRYeHRHS205dXlVNG1BTUpkT2F3VEg1YUM4VWdvV2EifQ",
  "has_more": true
}

Response#

A list of Ad objects in data.items, with data.cursor and data.has_more.

See Data models for every field. The envelope around data is described in Responses.

Errors#

Failures are free: credits_charged is 0. Branch on error.code, never on the message.

CodeHTTPRetryMeaning
invalid_params400noA parameter is missing, unknown or has the wrong type.
not_found404noThe platform says this profile, post or item does not exist.

Every request can also fail with the account and platform errors listed on the Errors page.

Also served at#

These paths answer the same request, so code written for other APIs keeps working: /v1/facebook/adLibrary/search/ads. See Switching from ScrapeCreators.