# Facebook Adlibrary Search Ads API (https://www.socialcrawl.dev/platforms/facebook/adlibrary-search-ads)

> Searches the Facebook Ad Library for ads matching a keyword. Returns matching ads with creative text, images, sponsor info, and status.

TL;DR: `GET /v1/facebook/adlibrary/search/ads` costs 5 credits per call and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `query` | yes | Search keyword or phrase to find ads in the Facebook Ad Library |
| `sort_by` | no | Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions. (total_impressions \| relevancy_monthly_grouped) |
| `search_type` | no | If you want to search by exact phrase or not (keyword_unordered \| keyword_exact_phrase) |
| `ad_type` | no | Search for all ads or only political and issue ads (all \| political_and_issue_ads) |
| `country` | no | This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL. |
| `status` | no | Status of the ad. Defaults to ACTIVE. (ALL \| ACTIVE \| INACTIVE) |
| `media_type` | no | Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme. (ALL \| IMAGE \| VIDEO \| MEME \| IMAGE_AND_MEME \| NONE) |
| `start_date` | no | Impressions start date. Needs to be in YYYY-MM-DD format. |
| `end_date` | no | Impressions end date. Needs to be in YYYY-MM-DD format. |
| `cursor` | no | Cursor to paginate through results |
| `trim` | no | Set to true for a trimmed down version of the response |

## Code example

```bash
curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/ads?query=artificial%20intelligence" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

## FAQ

### How do I search the Facebook Ad Library with an API?

Send a GET request to /v1/facebook/adlibrary/search/ads with your query keyword. SocialCrawl returns matching ads with creative text, images, sponsor info, status, impressions bucket, and date range.

### What search filters are supported?

Filter by country (2-letter code), status (ACTIVE/INACTIVE/ALL), media_type (IMAGE/VIDEO/MEME), ad_type (all or political_and_issue_ads), language, date range, and search_type (keyword_unordered or keyword_exact_phrase).

### Can I find winning creatives without scraping?

Yes. Search by keyword, sort by total_impressions (high to low), and the top hits are the highest-impression ads running for that query. Ideal for ad inspiration, creative research, and swipe-file building.

### How do I paginate through search results?

Take the cursor from the response and pass it as the cursor parameter on the next request. Continue until cursor is empty. Each page returns the same shape so your pagination loop stays simple across requests.

### Can I restrict results to political ads only?

Yes. Pass ad_type=political_and_issue_ads to return only political and issue ads. The response includes full transparency data — funding entity, targeting, and disclaimer — for policy research and civic tech use cases.

See the full Facebook API: https://www.socialcrawl.dev/platforms/facebook

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing

## Explore with AI

Questions this API answers, phrased for an AI assistant:

- How to search Facebook ads by keyword with the SocialCrawl API
- How to find winning competitor ads on Facebook