SocialScrape
Get early access
Docs menu

Get started

Guides

API reference

Resources

Facebook Ad Library ads by page (POST body)

Beta POST /v1/facebook/ad-library/company/ads

POST /v1/facebook/ad-library/company/ads

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
idstringone ofAd Library page id of the advertiser (from advertiser search). Also accepted as pageId, page_id.body
company_namestringone ofAdvertiser name (resolved to a page id). Also accepted as companyName.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
languagestringnoOnly ads in this language, a 2-letter code (EN, ES, FR). Also accepted as lang.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
start_datestringnoImpressions window start, YYYY-MM-DD.body
end_datestringnoImpressions window end, YYYY-MM-DD.body

Send at least one of id, company_name. If you send several, the first listed is used and the rest are ignored.

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/company/ads" \
  -H "x-api-key: $SOCIALSCRAPE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"id":"15087023444"}'
Python
import os
import requests

payload = {
    "id": "15087023444",
}
res = requests.post(
    "https://api.socialscrape.io/v1/facebook/ad-library/company/ads",
    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/company/ads", {
  method: "POST",
  headers: { "x-api-key": process.env.SOCIALSCRAPE_API_KEY!, "content-type": "application/json" },
  body: JSON.stringify({"id": "15087023444"}),
});
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_85776afc9704511f31f58dc8",
  "data": {
    "object": "list",
    "items": [
      {
        "object": "ad",
        "platform": "facebook",
        "id": "1016451784037642",
        "url": "https://www.facebook.com/ads/library/?id=1016451784037642",
        "advertiser": {
          "object": "advertiser",
          "platform": "facebook",
          "id": "15087023444",
          "name": "Nike",
          "url": "https://www.facebook.com/nike/",
          "page_id": "15087023444",
          "country": null,
          "verified": null,
          "ad_count": null,
          "extra": {
            "categories": [
              "Sportswear"
            ],
            "image_url": "https://scontent.fbna2-1.fna.fbcdn.net/v/t39.35426-6/509357337_4088170881445143_8138324132275675252_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=E54VvdMHySUQ7kNvwEnvChq&_nc_oc=AdqCjHz2Z3FCDYuoYTlBrei5fT0yOdXr6n78q...",
            "likes": 39491776
          }
        },
        "status": "active",
        "started_at": "2025-06-20T07:00:00Z",
        "ended_at": null,
        "title": "{{product.name}}",
        "body": "Get the gear that goes hard on and off the field.",
        "cta_text": "Shop now",
        "landing_url": "https://www.nike.com/us/en_us",
        "format": "dynamic_product",
        "media": {
          "thumbnail_url": null,
          "video_url": null,
          "audio_url": null,
          "image_urls": [
            "https://scontent.fcha1-1.fna.fbcdn.net/v/t39.35426-6/509094198_1485897442775736_2519419118144931021_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=yCKYUPvBXQQQ7kNvwHy1XqI&_nc_oc=AdrLnwg91W_KZPYr3dEXLa2Ig9AiYRSSr7klXFu5nrliot9duhhoIeNVyHDZ...",
            "https://scontent.fbna2-1.fna.fbcdn.net/v/t39.35426-6/508839160_1795820578003799_8147925336477608418_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=_nC5tWBvI38Q7kNvwGOJQwX&_nc_oc=AdrjalKY4JCxI9rGkqSVW5dvL8UBzt-fc7bsb-2zGySCqCC35zSjlU98iLm6...",
            "https://scontent.fcha1-1.fna.fbcdn.net/v/t39.35426-6/509269099_740526921689557_370794322046462071_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=pELkLSuCGYYQ7kNvwHdifKQ&_nc_oc=AdrqStQzy4BXqGZLyxi8Qozwqe2SzPHEjkOwuwAvojqZmrHD4XB4KiWPIgqu5U..."
          ],
          "width": null,
          "height": null
        },
        "regions": null,
        "publisher_platforms": [
          "facebook",
          "instagram"
        ],
        "impressions": null,
        "spend": null,
        "extra": {
          "caption": "NIKE.COM",
          "cards": [
            {
              "body": "Get the gear that goes hard on and off the field.",
              "cta_text": "Shop Now",
              "image_url": "https://scontent.fcha1-1.fna.fbcdn.net/v/t39.35426-6/509094198_1485897442775736_2519419118144931021_n.jpg?_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=yCKYUPvBXQQQ7kNvwHy1XqI&_nc_oc=AdrLnwg91W_KZPYr3dEXLa2Ig9AiYRSSr7klXFu5nrliot9duhhoIeNVyHDZ...",
              "link_url": "https://www.nike.com/t/air-monarch-iv-mens-workout-shoes-extra-wide-p8qNlT/416355-001?dplnk=member",
              "title": "Nike Air Monarch IV "
            },
            {
              "body": "Get the gear that goes hard on and off the field.",
              "cta_text": "Shop Now",
              "image_url": "https://scontent.fbna2-1.fna.fbcdn.net/v/t39.35426-6/508839160_1795820578003799_8147925336477608418_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=_nC5tWBvI38Q7kNvwGOJQwX&_nc_oc=AdrjalKY4JCxI9rGkqSVW5dvL8UBzt-fc7bsb-2zGySCqCC35zSjlU98iLm6...",
              "link_url": "https://www.nike.com/t/tempo-shorts-toddler-shorts-Gx0CH3/267358-019?dplnk=member",
              "title": "Nike Tempo Shorts "
            },
            {
              "body": "Get the gear that goes hard on and off the field.",
              "cta_text": "Shop Now",
              "image_url": "https://scontent.fcha1-1.fna.fbcdn.net/v/t39.35426-6/509269099_740526921689557_370794322046462071_n.jpg?_nc_cat=105&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=pELkLSuCGYYQ7kNvwHdifKQ&_nc_oc=AdrqStQzy4BXqGZLyxi8Qozwqe2SzPHEjkOwuwAvojqZmrHD4XB4KiWPIgqu5U...",
              "link_url": "https://www.nike.com/t/air-monarch-iv-mens-workout-shoes-extra-wide-p8qNlT/416355-102?dplnk=member",
              "title": "Nike Air Monarch IV "
            }
          ],
          "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-03T13:03:49Z",
          "regional_regulation_data": {
            "finserv": {
              "is_deemed_finserv": false,
              "is_limited_delivery": false
            },
            "tw_anti_scam": {
              "is_limited_delivery": false
            }
          }
        }
      },
      {
        "object": "ad",
        "platform": "facebook",
        "id": "1120113070497516",
        "url": "https://www.facebook.com/ads/library/?id=1120113070497516",
        "advertiser": {
          "object": "advertiser",
          "platform": "facebook",
          "id": "15087023444",
          "name": "Nike",
          "url": "https://www.facebook.com/nike/",
          "page_id": "15087023444",
          "country": null,
          "verified": null,
          "ad_count": null,
          "extra": {
            "categories": [
              "Sportswear"
            ],
            "image_url": "https://scontent.fcha1-1.fna.fbcdn.net/v/t39.35426-6/861252476_2084753155502396_8547913395286178715_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=111&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=qAjohwWFq84Q7kNvwHwiUzy&_nc_oc=AdqcUMir1RbfgLtklFpDaXefHkrqDADHr6ZjV...",
            "likes": 39491776
          }
        },
        "status": "active",
        "started_at": "2026-10-23T07:00:00Z",
        "ended_at": null,
        "title": "{{product.name}}",
        "body": "Get the gear not afraid to put in the work.",
        "cta_text": "Shop now",
        "landing_url": "https://www.nike.com/",
        "format": "dynamic_product",
        "media": {
          "thumbnail_url": null,
          "video_url": null,
          "audio_url": null,
          "image_urls": [
            "https://scontent.fbna2-1.fna.fbcdn.net/v/t39.35426-6/857775335_1482362137114094_8883723222350936326_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=VCYuEpQe4CYQ7kNvwH8z-rz&_nc_oc=AdpQ3Kj9C7CIp6255XNbWBqynfR6y1YvzkyxIGnrOsWAxpxJAJtnvzNdDV54...",
            "https://scontent.fcha1-1.fna.fbcdn.net/v/t39.35426-6/855497992_1677688053962186_291249616028421191_n.jpg?_nc_cat=109&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DTdAONcQPjkQ7kNvwE-b3w1&_nc_oc=AdoxXHssfMPGAAf1mOUrKToGqgOX5kPr92T9K7D3NlkRu4EfjyT96Af1smSpr...",
            "https://scontent.fbna2-1.fna.fbcdn.net/v/t39.35426-6/859082956_1149373757658736_8182143225806562368_n.jpg?_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=3KPeyrL1fd0Q7kNvwFHyLiY&_nc_oc=Adq3RbdVEbTucJeN4aL0CT7zYYIWMJSM6494vb-_bBCkTOnngrs2rZX0zZaf..."
          ],
          "width": null,
          "height": null
        },
        "regions": null,
        "publisher_platforms": [
          "facebook",
          "instagram"
        ],
        "impressions": null,
        "spend": null,
        "extra": {
          "caption": "NIKE.COM",
          "cards": [
            {
              "body": "Get the gear not afraid to put in the work.",
              "cta_text": "Shop Now",
              "image_url": "https://scontent.fbna2-1.fna.fbcdn.net/v/t39.35426-6/857775335_1482362137114094_8883723222350936326_n.jpg?_nc_cat=106&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=VCYuEpQe4CYQ7kNvwH8z-rz&_nc_oc=AdpQ3Kj9C7CIp6255XNbWBqynfR6y1YvzkyxIGnrOsWAxpxJAJtnvzNdDV54...",
              "link_url": "https://www.nike.com/t/air-monarch-iv-mens-workout-shoes-extra-wide-p8qNlT/416355-001?dplnk=member",
              "title": "Nike Air Monarch IV"
            },
            {
              "body": "Get the gear not afraid to put in the work.",
              "cta_text": "Shop Now",
              "image_url": "https://scontent.fcha1-1.fna.fbcdn.net/v/t39.35426-6/855497992_1677688053962186_291249616028421191_n.jpg?_nc_cat=109&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DTdAONcQPjkQ7kNvwE-b3w1&_nc_oc=AdoxXHssfMPGAAf1mOUrKToGqgOX5kPr92T9K7D3NlkRu4EfjyT96Af1smSpr...",
              "link_url": "https://www.nike.com/t/air-monarch-iv-mens-workout-shoes-p8qNlT/415445-001?dplnk=member",
              "title": "Nike Air Monarch IV"
            },
            {
              "body": "Get the gear not afraid to put in the work.",
              "cta_text": "Shop Now",
              "image_url": "https://scontent.fbna2-1.fna.fbcdn.net/v/t39.35426-6/859082956_1149373757658736_8182143225806562368_n.jpg?_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=3KPeyrL1fd0Q7kNvwFHyLiY&_nc_oc=Adq3RbdVEbTucJeN4aL0CT7zYYIWMJSM6494vb-_bBCkTOnngrs2rZX0zZaf...",
              "link_url": "https://www.nike.com/t/air-monarch-iv-mens-workout-shoes-p8qNlT/415445-102?dplnk=member",
              "title": "Nike Air Monarch IV"
            }
          ],
          "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-03T11:11:37Z",
          "regional_regulation_data": {
            "finserv": {
              "is_deemed_finserv": false,
              "is_limited_delivery": false
            },
            "tw_anti_scam": {
              "is_limited_delivery": false
            }
          }
        }
      }
    ],
    "cursor": "eyJrIjoiZmJhZHMiLCJjIjoiQVFIVEZfamZkd1hQZjYwUk9Ld3A0Qk1QeGlCM1BiN2pxYkc3dEtlbEhXSmJMc3hnb29XbnFjbWRnUUJCMEJ0Y3RGcW8iLCJwIjoiMTUwODcwMjM0NDQifQ",
    "has_more": true,
    "parent": {
      "object": "advertiser",
      "platform": "facebook",
      "id": "15087023444",
      "name": "Nike",
      "url": "https://www.facebook.com/nike/",
      "page_id": "15087023444",
      "country": null,
      "verified": null,
      "ad_count": 91,
      "extra": {
        "categories": [
          "Sportswear"
        ],
        "image_url": "https://scontent.fbna2-1.fna.fbcdn.net/v/t39.35426-6/509357337_4088170881445143_8138324132275675252_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=101&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=E54VvdMHySUQ7kNvwEnvChq&_nc_oc=AdqCjHz2Z3FCDYuoYTlBrei5fT0yOdXr6n78q...",
        "likes": 39491776
      }
    }
  },
  "cursor": "eyJrIjoiZmJhZHMiLCJjIjoiQVFIVEZfamZkd1hQZjYwUk9Ld3A0Qk1QeGlCM1BiN2pxYkc3dEtlbEhXSmJMc3hnb29XbnFjbWRnUUJCMEJ0Y3RGcW8iLCJwIjoiMTUwODcwMjM0NDQifQ",
  "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/company/ads. See Switching from ScrapeCreators.