# Facebook Ad Library Search API Beta Searches Meta's public Ad Library by keyword and returns the matching ads that ran on Facebook, Instagram, Messenger, Threads and the Audience Network: the advertiser's page, the days the ad first and last ran, whether it is still active, where it ran, and each creative's headline, text, link, call to action, images and videos. Political and social-issue ads also carry the disclosed payer and Meta's impressions, reach and spend ranges. Filter by country, language, active status and the day an ad first ran; results come in the Ad Library's own order, most impressions first. [Get 100 free credits](https://staging-fly.socialtap.dev/signup/?next=%2Fplayground%2F%3Fendpoint%3Dfacebook.search_ads) · [API reference](https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md) · [Try it](https://staging-fly.socialtap.dev/playground/?endpoint=facebook.search_ads) - **Price**: From **1 credit** per page$0.75–$1.45 per 1,000 pages - **Request**: `GET /v1/facebook/search_ads`One API key, one JSON schema - **Input**: `query`e.g. `coffee` - **Page size**: Up to 10 ads Use cases ## What teams build with it. From one request. - Monitor competitors' ad creatives and offers - Research ad copy in a market or niche - Track political and issue ad spending - Find the advertisers running ads on a topic What you get ## Ads in one schema. The same on every platform. - **`platform`string**: Library owner's platform ID (facebook for Meta's library, tiktok, google, linkedin). - **`id`string**: Library ad ID (string). - **`url`string**: Public library page of the ad. - **`advertiser`object**: The advertising page, business or account. - **`paid_by`string**: Disclosed payer ("Paid for by"). - **`is_active`boolean**: True while the ad is running. - **`first_shown_at`string**: First delivery, RFC 3339 UTC (often date-only: see approximate_fields). - **`last_shown_at`string**: Last delivery, RFC 3339 UTC; null while active. Every field, its type and when it is `null`: [the response reference](https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md#response) and the [ad schema](https://staging-fly.socialtap.dev/resources/ad/index.md). ## Example request cURL: ```shell curl -G 'https://staging-fly.socialtap.dev/v1/facebook/search_ads' \ --data-urlencode 'country=US' \ --data-urlencode 'query=coffee' \ --data-urlencode 'status=all' \ -H "x-api-key: $SOCIALTAP_API_KEY" ``` Node.js: ```javascript const params = new URLSearchParams({ country: "US", query: "coffee", status: "all", }); const res = await fetch(`https://staging-fly.socialtap.dev/v1/facebook/search_ads?${params}`, { headers: { "x-api-key": process.env.SOCIALTAP_API_KEY ?? "" }, }); const body = await res.json(); if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`); const { data, page, meta } = body; console.log(data, meta.credits_charged); ``` Python: ```python import os import requests res = requests.get( "https://staging-fly.socialtap.dev/v1/facebook/search_ads", params={"country": "US", "query": "coffee", "status": "all"}, headers={"x-api-key": os.environ["SOCIALTAP_API_KEY"]}, ) body = res.json() if not res.ok: raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}") data, page, meta = body["data"], body["page"], body["meta"] print(data, meta["credits_charged"]) ``` Go: ```go package main import ( "encoding/json" "fmt" "log" "net/http" "net/url" "os" ) func main() { q := url.Values{} q.Set("country", "US") q.Set("query", "coffee") q.Set("status", "all") req, err := http.NewRequest("GET", "https://staging-fly.socialtap.dev/v1/facebook/search_ads?"+q.Encode(), nil) if err != nil { log.Fatal(err) } req.Header.Set("x-api-key", os.Getenv("SOCIALTAP_API_KEY")) res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var body struct { Data json.RawMessage `json:"data"` Page json.RawMessage `json:"page"` Meta map[string]any `json:"meta"` Error *struct { Code string `json:"code"` Message string `json:"message"` } `json:"error"` } if err := json.NewDecoder(res.Body).Decode(&body); err != nil { log.Fatal(err) } if body.Error != nil { log.Fatalf("%s: %s", body.Error.Code, body.Error.Message) } fmt.Println(string(body.Data), body.Meta["credits_charged"]) } ``` 200 OK: ```json { "data": [ { "advertiser": { "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/739782028_1533198008291919_1079542453788497101_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&…", "display_name": "American Health Support Community", "id": "966175593248497", "is_verified": null, "url": "https://www.facebook.com/61588018263996", "username": null }, "approximate_fields": [ "first_shown_at" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": "My aunt called me a creep for putting a camera in Nana’s living room.\n\nNana called me practical.\n\nThen the camera caught something worse than a fall.\n\nI need to be clear about one thing before anyone decides what kind of grandson I am.\n\nNana asked for the camera.\n\nNot me.\n\nNot my…", "cta_text": "Learn more", "link_description": null, "link_url": "https://shop.pipitea.com/hbt/kd/sp-nm", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/742001725_2100792434176297_9060645049521596104_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=100&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/742501415_1706621370582971_4085631001896338504_n.jpg?_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Natural Relief in Weeks" } ], "first_shown_at": "2026-07-18T07:00:00Z", "id": "2619351891814847", "impressions": null, "is_active": true, "is_political": false, "languages": [], "last_shown_at": null, "paid_by": null, "platform": "facebook", "platform_specific": {}, "publisher_platforms": [ "facebook", "instagram", "audience_network" ], "reach": null, "spend": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/ads/library/?id=2619351891814847" }, { "advertiser": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/712623693_1599994994434095_1320701223312676781_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=110&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&…", "display_name": "American Health Support Community", "id": "966175593248497", "is_verified": null, "url": "https://www.facebook.com/61588018263996", "username": null }, "approximate_fields": [ "first_shown_at" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": "I almost looked past the woman who saved my husband's life. She was seventy-nine, sitting alone at the booth next to ours at the Cracker Barrel off Highway 31. A glass of milk in front of her. She kept stirring it. She wasn't eating.\n\nIf I'd known, the night I leaned over and ask…", "cta_text": "Learn more", "link_description": "\"I've tried everything to support my kidney function naturally. Fish oil, CoQ10, cutting protein, stressing about every meal. Nothing moved the needle enough to satisfy my doctor. Hibiscus tea is the first thing that actually showed up in my numbers. It's been 3 months and my eGF…", "link_url": "https://shop.pipitea.com/hbt/kd/sp", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/711729685_1717035472767079_186136568392095276_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED…", "type": "image", "url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/713729791_868879862958547_7409366389733397444_n.jpg?_nc_cat=107&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Natural Relief in Weeks" } ], "first_shown_at": "2026-06-01T07:00:00Z", "id": "1923645134954720", "impressions": null, "is_active": true, "is_political": false, "languages": [], "last_shown_at": null, "paid_by": null, "platform": "facebook", "platform_specific": {}, "publisher_platforms": [ "facebook", "instagram", "audience_network" ], "reach": null, "spend": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/ads/library/?id=1923645134954720" }, { "advertiser": { "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/712025330_1303417705276292_736671271727941526_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&o…", "display_name": "American Health Support Community", "id": "966175593248497", "is_verified": null, "url": "https://www.facebook.com/61588018263996", "username": null }, "approximate_fields": [ "first_shown_at" ], "audience_size": null, "country_codes": [], "creatives": [ { "body": "I almost looked past the woman who saved my husband's life. She was seventy-nine, sitting alone at the booth next to ours at the Cracker Barrel off Highway 31. A glass of milk in front of her. She kept stirring it. She wasn't eating.\n\nIf I'd known, the night I leaned over and ask…", "cta_text": "Learn more", "link_description": "\"I've tried everything to support my kidney function naturally. Fish oil, CoQ10, cutting protein, stressing about every meal. Nothing moved the needle enough to satisfy my doctor. Hibiscus tea is the first thing that actually showed up in my numbers. It's been 3 months and my eGF…", "link_url": "https://shop.pipitea.com/hbt/kd/sp", "media": [ { "alt_text": null, "duration_ms": null, "expires_at": "2026-10-25T18:00:00Z", "height": null, "thumbnail_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.35426-6/711737708_4485707625086258_2353150069319301753_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=109&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBE…", "type": "image", "url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.35426-6/710755472_911440771966686_1736050619245168045_n.jpg?_nc_cat=111&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=14&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_nc_ss=7b289&oh=SCRUBBED&oe=F2A52380", "width": null } ], "title": "Natural Relief in Weeks" } ], "first_shown_at": "2026-06-01T07:00:00Z", "id": "2140497416496021", "impressions": null, "is_active": true, "is_political": false, "languages": [], "last_shown_at": null, "paid_by": null, "platform": "facebook", "platform_specific": {}, "publisher_platforms": [ "facebook", "instagram", "audience_network" ], "reach": null, "spend": null, "type": "image", "unknown_fields": [], "url": "https://www.facebook.com/ads/library/?id=2140497416496021" } ], "page": { "has_more": true, "next_cursor": "c1.EXAMPLE_CURSOR", "next_cursor_expires_at": "2026-10-26T12:00:00Z", "end_reason": null }, "meta": { "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f", "platform": "facebook", "source": "api", "is_cached": false, "credits_charged": 1, "latency_ms": 0, "fetched_at": "2026-10-25T12:00:00Z", "input": null, "credits_remaining": 9999, "client_request_id": null, "warnings": [], "mode": "live" } } ``` Long arrays and strings are shortened for display; real responses are complete. > [!NOTE] > > **Good to know** > > - Payer, impressions, reach and spend are disclosed only for political and social-issue ads; they are null for other ads. > - Dates are whole days (Meta reports the day an ad first and last ran, US Pacific time), so they are listed in approximate_fields. > - since and until return the ads that ran during the window (first ran before until, and still running or last ran at or after since), whole days as Meta reports them; a filtered page can hold fewer ads than the page size, and that is not the end of the list. > - Ads that share one creative are grouped by Meta; each ad of a group is returned as its own item. > - Languages, targeting and EU reach by country are not part of the search results; those fields are empty or null. Pricing ## Pay per page. Only when it succeeds. | Source | Price per successful page | Per 1,000 pages | | --- | --- | --- | | Platform API `api` | 1 credit | $0.75–$1.45 | - Failed requests are free: errors cost 0 credits. - Cache hits are free: responses served from the cache cost 0 credits. - Credits never expire. - One credit balance for every endpoint and platform. [Credit packs](https://staging-fly.socialtap.dev/pricing/index.md) · [How this endpoint is priced](https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md#pricing) · [How credits work](https://staging-fly.socialtap.dev/docs/credits/index.md) FAQ ## Questions, answered. **How do I search for an exact phrase?** Wrap the query in double quotes, for example "cold brew"; without quotes every word must appear, in any order. **Which ads does it find?** Every ad in Meta's public Ad Library whose text matches the query: active and inactive ads on all of Meta's apps, from any advertiser. **How much does the Facebook Ad Library Search API cost?** 1 credit for platform api results (meta.source = api) per page of up to 10 items, charged for every successful page, empty pages included. SocialTap credits cost $0.75–$1.45 per 1,000 depending on the pack. **How do I get the next page?** Repeat the same request with cursor set to page.next_cursor from the previous response, keeping the other parameters. When page.has_more is false there are no more items. Cursors expire after 1 hour. **Am I charged for failed requests?** No. Requests that return an error cost 0 credits. Responses served from the cache are free too. More Facebook ## Facebook API. 3 endpoints, one key. [Facebook Post APIBetaPost`GET /v1/facebook/post`1 credit](https://staging-fly.socialtap.dev/apis/facebook/post/index.md) · [Facebook Video Transcript APIBetaTranscript`GET /v1/facebook/transcript`From 1 credit](https://staging-fly.socialtap.dev/apis/facebook/transcript/index.md) ## Start with 100 free credits. No card required. Test keys answer every endpoint from recorded responses, free, so you can build before you spend. Failed requests are always free. [Get your API key](https://staging-fly.socialtap.dev/signup/?next=%2Fplayground%2F%3Fendpoint%3Dfacebook.search_ads) · [Read the API reference](https://staging-fly.socialtap.dev/docs/reference/facebook/search_ads/index.md) --- [HTML version](https://staging-fly.socialtap.dev/apis/facebook/search_ads/) · [Docs index for AI agents](https://staging-fly.socialtap.dev/llms.txt) · [All docs in one file](https://staging-fly.socialtap.dev/llms-full.txt)