CaptapiCaptapi
Facebook Ad Library
GET /v1/ad-library/facebook/company-ads

Facebook Company Ads API

Ads for one Meta page — active by default, Meta's top-by-impressions order, sort_by and date window, same envelope as /facebook/search.

2 credits per request
Try in PlaygroundGet your API key — freeRead the docs
TL;DR
Ads for one Meta page — active by default, Meta's top-by-impressions order, sort_by and date window, same envelope as /facebook/search. The Facebook Company Ads API (Facebook Ad Library) is a single authenticated GET request to /v1/ad-library/facebook/company-ads that responds with clean JSON and costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh. Start with 100 free credits — no credit card.

What is the Facebook Company Ads API?

List ads for one Meta page/advertiser. Prefer pageId (or libraryUrl) from /facebook/search-companies. status defaults to ACTIVE so the first page is what the page is running now — use ALL for historical/inactive variants (collation siblings share copy and consume a limit slot). Default order is Meta's ranking — top ads by impressions first, not newest first; sort_by (total_impressions|relevancy_monthly_grouped) sets it explicitly. Meta serves about 30 ads per library page; a limit above 30 also scrolls the library for more, up to ~70–80 per call (~45–60s). start_date/end_date (YYYY-MM-DD, same as /facebook/search) filter by delivery date: ads shown at any point in the range, not ads that started in it — so a window narrows the list, it does not reach ads beyond the batch. nextCursor pages that fetched batch; hasMore is true only when nextCursor is present, and null with truncatedReason=library-page when the batch is spent but Meta still has more ads. searchResultsCount is Meta's upstream match count; retrievableCount is how many ads this cursor walk can actually return. A search-companies libraryUrl with active_status=all is rewritten to the requested filter (sort_by and dates likewise replace any the link carried). Flat 2 credits; an empty result is 0 credits.

What you get

  • Bulk list of company ads with metadata
  • Dates, URLs, and engagement fields when available
  • Configurable result limit
  • Ideal for monitoring and content pipelines

Try it

Open in Playground

Fill in the parameters below and copy a ready-to-run request, or open the live Playground to run it against your account (no API key paste).

Parameters

Sign in to run live
curl "https://api.captapi.com/v1/ad-library/facebook/company-ads?url=15087023444" \
  -H "Authorization: Bearer capt_live_..."
# or: -H "x-api-key: capt_live_..."

Edit the parameters and the code updates instantly. Switch languages and hit copy.

Example response

{
  "success": true,
  "data": {
    "url": "15087023444",
    "country": "US",
    "status": "ACTIVE",
    "limit": 10,
    "totalReturned": 2,
    "searchResultsCount": 94,
    "retrievableCount": 30,
    "hasMore": true,
    "nextCursor": "eyJhIjoiMTQyOTE0OTg4MjA3MTExNyJ9",
    "truncatedReason": null,
    "ads": [
      {
        "platform": "facebook",
        "id": "1016451784037642",
        "url": "https://www.facebook.com/ads/library/?id=1016451784037642",
        "text": "Get the gear that goes hard on and off the field.",
        "headline": "Nike Air Monarch IV",
        "cta": "Shop now",
        "landingUrl": "https://www.nike.com/us/en_us",
        "adFormat": "DPA",
        "firstShown": "2025-06-20",
        "lastShown": "2025-08-28",
        "impressions": null,
        "spend": null,
        "advertiser": {
          "id": "15087023444",
          "name": "Nike",
          "url": "https://www.facebook.com/nike/",
          "logo": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/509357337_4088170881445143_8138324132275675252_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=101&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=E54VvdMHySUQ7kNvwFHwJVT&_nc_oc=AdoxNxasX5Ywe3oK2wkg6X8K40EbkQhQnKS1IqG8o9CK0pEO7UKmGcF3BEId7THpSJE&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQRsxP1yl1ZXJtuu49-eYS-f5a6NmsljLRQ7i_DUVeoVIA&oe=6AEA8802",
          "location": null
        },
        "media": [
          "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/508595289_3894423190809901_7283310637062104285_n.jpg?_nc_cat=100&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DNIRItpAsqAQ7kNvwELWxDq&_nc_oc=Adp76AejgVIVQqeevGE65LiBhITRHStG2aJ-cljxupCaI-BVBUMPPX1laJzPfsC2tMw&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQRhiWKjusGy_z6UU9i9v2DFJ-7-zBmDf9Gu2vsjVGArQA&oe=6AEA9A07",
          "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/508839160_1795820578003799_8147925336477608418_n.jpg?_nc_cat=100&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=wKVALl_HL8cQ7kNvwHx0uQu&_nc_oc=Adr7DMIGlkw6Ye3RRkWF0hYEEiBpz8vaRYHkdo13p-z-rL9j51Kg10-1-n734hc4L8k&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQTDvHinDMEG7LqR4jjRewlfooZbkLOAsDRwZWGvQE-Kbg&oe=6AEA6E41"
        ],
        "isActive": true,
        "publisherPlatforms": [
          "FACEBOOK",
          "INSTAGRAM"
        ],
        "ctaType": "SHOP_NOW",
        "caption": "NIKE.COM",
        "linkDescription": null,
        "brandedContent": null,
        "disclaimerLabel": null,
        "byline": null,
        "reachEstimate": null,
        "reachEstimateRange": null,
        "totalActiveTime": null,
        "politicalCountries": [],
        "pageLikeCount": 39491281,
        "pageCategories": [
          "Sportswear"
        ],
        "pageEntityType": null,
        "cards": [
          {
            "text": "Get the gear that goes hard on and off the field.",
            "headline": "Nike Air Monarch IV",
            "cta": "Shop Now",
            "landingUrl": "https://www.nike.com/t/air-monarch-iv-mens-workout-shoes-p8qNlT/415445-102?dplnk=member",
            "linkDescription": null,
            "caption": "nike.com",
            "imageUrl": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/508595289_3894423190809901_7283310637062104285_n.jpg?_nc_cat=100&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DNIRItpAsqAQ7kNvwELWxDq&_nc_oc=Adp76AejgVIVQqeevGE65LiBhITRHStG2aJ-cljxupCaI-BVBUMPPX1laJzPfsC2tMw&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQRhiWKjusGy_z6UU9i9v2DFJ-7-zBmDf9Gu2vsjVGArQA&oe=6AEA9A07",
            "videoUrl": null,
            "videoPreviewUrl": null
          },
          {
            "text": "Get the gear that goes hard on and off the field.",
            "headline": "Nike Tempo Shorts",
            "cta": "Shop Now",
            "landingUrl": "https://www.nike.com/t/tempo-shorts-toddler-shorts-Gx0CH3/267358-019?dplnk=member",
            "linkDescription": null,
            "caption": "nike.com",
            "imageUrl": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/508839160_1795820578003799_8147925336477608418_n.jpg?_nc_cat=100&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=wKVALl_HL8cQ7kNvwHx0uQu&_nc_oc=Adr7DMIGlkw6Ye3RRkWF0hYEEiBpz8vaRYHkdo13p-z-rL9j51Kg10-1-n734hc4L8k&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQTDvHinDMEG7LqR4jjRewlfooZbkLOAsDRwZWGvQE-Kbg&oe=6AEA6E41",
            "videoUrl": null,
            "videoPreviewUrl": null
          }
        ],
        "images": [
          {
            "url": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/508595289_3894423190809901_7283310637062104285_n.jpg?_nc_cat=100&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DNIRItpAsqAQ7kNvwELWxDq&_nc_oc=Adp76AejgVIVQqeevGE65LiBhITRHStG2aJ-cljxupCaI-BVBUMPPX1laJzPfsC2tMw&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQRhiWKjusGy_z6UU9i9v2DFJ-7-zBmDf9Gu2vsjVGArQA&oe=6AEA9A07",
            "resizedUrl": null
          },
          {
            "url": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/508839160_1795820578003799_8147925336477608418_n.jpg?_nc_cat=100&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=wKVALl_HL8cQ7kNvwHx0uQu&_nc_oc=Adr7DMIGlkw6Ye3RRkWF0hYEEiBpz8vaRYHkdo13p-z-rL9j51Kg10-1-n734hc4L8k&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQTDvHinDMEG7LqR4jjRewlfooZbkLOAsDRwZWGvQE-Kbg&oe=6AEA6E41",
            "resizedUrl": null
          }
        ],
        "videos": [],
        "spendRange": null,
        "impressionsRange": null,
        "variantCount": null,
        "collationId": null,
        "isAaaEligible": false,
        "textIsFromCard": true,
        "mediaUrlsExpireAt": "2026-11-03T23:29:05.000Z"
      },
      {
        "platform": "facebook",
        "id": "1120113070497516",
        "url": "https://www.facebook.com/ads/library/?id=1120113070497516",
        "text": "Get the gear not afraid to put in the work.",
        "headline": "Nike Air Monarch IV",
        "cta": "Shop now",
        "landingUrl": "https://www.nike.com/",
        "adFormat": "DPA",
        "firstShown": "2026-10-23",
        "lastShown": "2026-10-30",
        "impressions": null,
        "spend": null,
        "advertiser": {
          "id": "15087023444",
          "name": "Nike",
          "url": "https://www.facebook.com/nike/",
          "logo": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/861252476_2084753155502396_8547913395286178715_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=111&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=qAjohwWFq84Q7kNvwFXqVer&_nc_oc=AdqIBU4IyfNUnUwVVX3eFpJvO6t2f0-SCmNYOctLg7OHCzMHCXdubBaTWXIV_ZgtLps&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQQju2tKSIrvmc4CkcYVvUX3hFbDOa00XilCh39Xsnajdg&oe=6AEA7055",
          "location": null
        },
        "media": [
          "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/857775335_1482362137114094_8883723222350936326_n.jpg?_nc_cat=106&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=VCYuEpQe4CYQ7kNvwHe5WGs&_nc_oc=Adp0IiA30hxw8LMCZwFB1e8fYHX2uPSglGtMl4SSPmwxSBzfg_rZJUJC5e9bvNN09ys&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQRf-f1isKNu9tLzP9emcQua-LBlMARLWtbAXsOUgZYmIQ&oe=6AEA6A29",
          "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/855926891_29311883145076276_4903153815934868367_n.jpg?_nc_cat=103&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=kZYTJa6slvEQ7kNvwH9VSi3&_nc_oc=AdocW7OVYAEBYfFrg1JcOeYYQXso2x6TrquoX0dzPrEXG8MVvbi-Dvk6wZKpGRarYIM&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQTTOQUA79hZv7ekj7xw7YsFkn0wwinrQBkBFjG0mN9S8Q&oe=6AEA7504"
        ],
        "isActive": true,
        "publisherPlatforms": [
          "FACEBOOK",
          "INSTAGRAM"
        ],
        "ctaType": "SHOP_NOW",
        "caption": "NIKE.COM",
        "linkDescription": null,
        "brandedContent": null,
        "disclaimerLabel": null,
        "byline": null,
        "reachEstimate": null,
        "reachEstimateRange": null,
        "totalActiveTime": null,
        "politicalCountries": [],
        "pageLikeCount": 39491281,
        "pageCategories": [
          "Sportswear"
        ],
        "pageEntityType": null,
        "cards": [
          {
            "text": "Get the gear not afraid to put in the work.",
            "headline": "Nike Air Monarch IV",
            "cta": "Shop Now",
            "landingUrl": "https://www.nike.com/t/air-monarch-iv-mens-workout-shoes-extra-wide-p8qNlT/416355-001?dplnk=member",
            "linkDescription": "Nike delivers innovative products, experiences and services to inspire athletes.",
            "caption": "nike.com",
            "imageUrl": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/857775335_1482362137114094_8883723222350936326_n.jpg?_nc_cat=106&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=VCYuEpQe4CYQ7kNvwHe5WGs&_nc_oc=Adp0IiA30hxw8LMCZwFB1e8fYHX2uPSglGtMl4SSPmwxSBzfg_rZJUJC5e9bvNN09ys&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQRf-f1isKNu9tLzP9emcQua-LBlMARLWtbAXsOUgZYmIQ&oe=6AEA6A29",
            "videoUrl": null,
            "videoPreviewUrl": null
          },
          {
            "text": "Get the gear not afraid to put in the work.",
            "headline": "Nike Tempo Shorts",
            "cta": "Shop Now",
            "landingUrl": "https://www.nike.com/t/tempo-shorts-toddler-shorts-Gx0CH3/267358-019?dplnk=member",
            "linkDescription": "Nike delivers innovative products, experiences and services to inspire athletes.",
            "caption": "nike.com",
            "imageUrl": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/855926891_29311883145076276_4903153815934868367_n.jpg?_nc_cat=103&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=kZYTJa6slvEQ7kNvwH9VSi3&_nc_oc=AdocW7OVYAEBYfFrg1JcOeYYQXso2x6TrquoX0dzPrEXG8MVvbi-Dvk6wZKpGRarYIM&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQTTOQUA79hZv7ekj7xw7YsFkn0wwinrQBkBFjG0mN9S8Q&oe=6AEA7504",
            "videoUrl": null,
            "videoPreviewUrl": null
          }
        ],
        "images": [
          {
            "url": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/857775335_1482362137114094_8883723222350936326_n.jpg?_nc_cat=106&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=VCYuEpQe4CYQ7kNvwHe5WGs&_nc_oc=Adp0IiA30hxw8LMCZwFB1e8fYHX2uPSglGtMl4SSPmwxSBzfg_rZJUJC5e9bvNN09ys&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQRf-f1isKNu9tLzP9emcQua-LBlMARLWtbAXsOUgZYmIQ&oe=6AEA6A29",
            "resizedUrl": null
          },
          {
            "url": "https://scontent.ftce2-1.fna.fbcdn.net/v/t39.35426-6/855926891_29311883145076276_4903153815934868367_n.jpg?_nc_cat=103&_nc_map=urlgen_bucketless&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=kZYTJa6slvEQ7kNvwH9VSi3&_nc_oc=AdocW7OVYAEBYfFrg1JcOeYYQXso2x6TrquoX0dzPrEXG8MVvbi-Dvk6wZKpGRarYIM&_nc_zt=14&_nc_ht=scontent.ftce2-1.fna&_nc_gid=4I91YQgS19BP4K2VBs0HmQ&_nc_ss=7b289&oh=00_AQTTOQUA79hZv7ekj7xw7YsFkn0wwinrQBkBFjG0mN9S8Q&oe=6AEA7504",
            "resizedUrl": null
          }
        ],
        "videos": [],
        "spendRange": null,
        "impressionsRange": null,
        "variantCount": null,
        "collationId": null,
        "isAaaEligible": false,
        "textIsFromCard": true,
        "mediaUrlsExpireAt": "2026-11-03T23:11:37.000Z"
      }
    ],
    "fetchMs": 11946,
    "parseMs": 28,
    "totalMs": 11974,
    "fetchedAt": "2026-10-30T14:53:24.834Z"
  }
}

Billing metadata is returned in response headers: X-Captapi-Credits (credits charged), X-Captapi-Cache (hit or miss), and X-Captapi-Request-Id (include it when contacting support). Where the response has a source field, it names the path that served the data: native, extended, cache or asr. Failed requests (4xx/5xx) are never charged. See the full list of error codes in the error reference.

Response structure

A successful call returns success and a data object with the following fields:

Top-level fields

  • urlCanonical URL of the item.
  • countryISO market you queried (e.g. US). Envelope only — not a popular-creators feed market.
  • statusAd delivery filter echoed: ACTIVE, INACTIVE, or ALL.
  • limitlimit you asked for.
  • totalReturnedAds on this page (length of ads[]).
  • searchResultsCountMeta's upstream match count — can be thousands and can move between calls. Not how many ads this endpoint can return.
  • retrievableCountAds in the fetched HTML batch after the status filter; the cursor walk ends when this many have been delivered.
  • hasMoreTrue only when nextCursor is present.
  • nextCursorOpaque cursor for the next slice of this HTML batch (base64 of the last ad id). null means this walk is done — pass status=ALL or refine filters, do not invent a cursor.
  • truncatedReasonTruncated reason.
  • fetchMsFetch ms. Example: 11946.
  • parseMsParse ms. Example: 28.
  • totalMsTotal ms. Example: 11974.
  • fetchedAtWhen this snapshot was fetched (ISO 8601 UTC).

Ads

Each item in ads contains:

  • platformPlatform identifier for this response (matches the endpoint's platform).
  • idId of this ads item.
  • urlCanonical URL of the item.
  • textText content.
  • headlineAd headline / title when Meta exposes it. Not a profile headline.
  • ctaCall-to-action text.
  • landingUrlLanding page the ad links to.
  • adFormatFormat of the ad creative.
  • firstShownMeta delivery-start date as YYYY-MM-DD (Pacific calendar day).
  • lastShownMeta delivery-end date as YYYY-MM-DD (Pacific calendar day).
  • impressionsEstimated ad impressions.
  • spendEstimated ad spend.
  • advertiserAdvertiser running the ad.
  • mediaMedia attached to the item.
  • isActiveWhether the ad is currently eligible for delivery.
  • publisherPlatformsWhere the ad ran (FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, …).
  • ctaTypeCta type. Example: "SHOP_NOW".
  • captionPost or creative caption when the platform exposes one.
  • linkDescriptionLink description / preview text under the creative.
  • brandedContentBranded-content metadata when present.
  • disclaimerLabelTransparency disclaimer text (e.g. "Paid for by …").
  • bylinePaid-for-by / byline string when Meta exposes one.
  • reachEstimateMeta reach estimate display string when published (often political/issue ads only).
  • reachEstimateRangeParsed reachEstimate as {min, max, raw}.
  • totalActiveTimeTotal active delivery time in seconds when Meta exposes it.
  • politicalCountriesCountries where the ad is classified as political/issue.
  • pageLikeCountAdvertiser Facebook Page like count (spam/size signal).
  • pageCategoriesAdvertiser Page categories from Meta.
  • pageEntityTypeAdvertiser entity type (e.g. PERSON_PROFILE, PAGE).
  • cardsCarousel cards with per-card text, CTA, landing URL, and media.
  • imagesAttached image URL list for this item.
  • videosVideos related to this result — meaning depends on the endpoint (integer count vs typed asset list). Prefer the field note on this page.
  • spendRangeParsed spend as {min, max, currency, raw}. Prefer this for sorting; spend stays the Meta display string. Usually null for commercial ads.
  • impressionsRangeParsed impressions as {min, max, raw}. Prefer this for sorting; impressions stays the Meta display string. Usually null for commercial ads.
  • variantCountVariant count.
  • collationIdCollation id.
  • isAaaEligibleIs aaa eligible. Example: false.
  • textIsFromCardText is from card. Example: true.
  • mediaUrlsExpireAtISO-8601 UTC earliest expiry across signed media URLs in this response (expire= / x-expires / TikTok hex path timestamp). Null when no stamp is parseable — never a guess.

Parameters

NameTypeRequiredDescription
urlstringYespageId from /search-companies (preferred), libraryUrl, vanity page URL (facebook.com/nike/), or Ad Library URL with view_all_page_id. Do not pass profileId from facebook.com/{digits}/ when it differs from pageId. The URL platform must match this endpoint's platform. Do not pass cross-platform URLs, e.g. YouTube to TikTok, Instagram to Facebook, LinkedIn to X/Twitter, or Pinterest to Rumble.
countrystringNoTwo-letter ISO country code, or ALL for every country (Meta's own value). Default US. For inactive ads prefer ALL: a single-country search can list far fewer inactive ads than ALL. Other non-ISO codes are a definitive 400 INVALID_COUNTRY.
limitintegerNoMax items to return (default 20, max 200). Flat 2 credits per call on the native path; the extended fallback bills per returned ad.
statusstringNoAd delivery status: ACTIVE (default), INACTIVE, or ALL. Use ACTIVE for "what are they running now?".
sort_bystringNoMeta sort mode: total_impressions or relevancy_monthly_grouped. Omit for Meta's default ranking (top ads by impressions first).
start_datestringNoOnly ads shown (delivered) on or after this date (YYYY-MM-DD). Delivery-date window, not a start-date filter: an ad that started earlier but was still running in the range is included.
end_datestringNoOnly ads shown (delivered) on or before this date (YYYY-MM-DD).
cursorstringNoPagination cursor from a previous nextCursor. Pages through the current Meta HTML result batch.
cachebooleanNoSet true to serve from the 24h response cache (0 credits on hit). Default false — always fetch fresh.

Authentication: send your key as Authorization: Bearer capt_live_.... A typical call costs 2 credits. Pass cache=true for a free 24h cache hit; default is always fresh.

Using an AI agent? This endpoint is the MCP tool facebook_ad_library_company_ads via @captapi/mcp. Set it up →

How it works

  1. 1. Sign up — get 100 free credits, no card required.
  2. 2. Create a key from your dashboard.
  3. 3. Send one request to /v1/ad-library/facebook/company-ads and parse the JSON response.

Use cases

Discovery

Surface items matching a topic, tag, sound, or trend query.

Monitoring

Watch a list feed over time for new activity.

Research

Sample structured list results for analysis.

Pipelines

Ingest list results into your own store or CRM.

Frequently asked questions

What does the Facebook Company Ads API do?+

The Facebook Company Ads API lets you list items in bulk with metadata from a public Facebook Ad Library ad using one GET request to /v1/ad-library/facebook/company-ads. It returns clean JSON — no OAuth or infrastructure setup required.

How many credits does the Facebook Company Ads API cost?+

Each successful call costs 2 credits. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Failed or empty results are never charged.

Do I need a Facebook Ad Library API key or OAuth?+

No. A single Captapi key works across every platform Captapi supports — YouTube, TikTok, Instagram, Facebook, Twitter/X, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Rumble, Spotify, Kwai, and more. We handle access, rate limits, retries, and authentication for you.

Is the Facebook Company Ads API suitable for production use?+

Yes. It is a stable REST endpoint with predictable JSON and automatic retries. Pass cache=true to serve from the 24h cache (0 credits on hit); default is always fresh. Selected profile endpoints also accept cacheMaxAge=1d|3d|7d|14d|30d. Use it for analytics, monitoring, and content automation.

More Facebook Ad Library APIs

Facebook Ad Library Search APIFacebook Ad Library Search Companies APIFacebook Ad Details APIFacebook Ad Transcript API

Ready to use the Facebook Company Ads API?

Sign up, grab your key, and make your first call in 60 seconds.

Get started free
Facebook Company Ads API — Captapi