# Facebook Ad Library API (ScrapeIO)

5 endpoints for public Facebook Ad Library data. Same response format and field names as every other platform.

## Basics

- Base URL: `https://scrapeio.com`
- Auth: send your key in the `x-api-key` header. Get a key at https://scrapeio.com/login (100 free credits, no card).
- Every endpoint is a GET with query parameters and returns JSON:
  `{ "success": true, "cached": false, "credits_used": 1, "credits_remaining": 99, "data": { ... } }`
- Field names are the same on every platform (`handle`, `followers`, `plays`, `likes`, `comments`, `created_at`).
- Lists return `data.items`, `data.cursor` and `data.has_more`. Pass `cursor` back to get the next page.
- Each endpoint has one listed price. Cached repeats, failed calls, private and not-found answers cost 0.
- Limit: 300 requests a minute per key.

## Errors

| Status | Meaning | Charged |
| --- | --- | --- |
| 200 | Success | Yes, unless cached |
| 400 | A parameter is missing or wrong | No |
| 401 | The key is missing or invalid | No |
| 402 | Not enough credits | No |
| 403 | The account or post is private | No |
| 404 | Not found on the platform | No |
| 429 | More than 300 requests a minute | No |
| 502 | Every source is down; retry shortly | No |

### GET /v1/facebook/adLibrary/ad

Ad Details Price: 5 credits. MCP tool: `facebook_adlibrary_ad`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | Facebook Ad Id |
| `url` | string | no | Facebook Ad URL |
| `get_transcript` | boolean | no | Transcription is opt-in via gettranscript=true. |
| `trim` | boolean | no | Set to true for a trimmed down version of the response |
| `cache_max_age` | string (1d, 3d, 7d, 14d, 30d) | no | If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "ca |

```bash
curl "https://scrapeio.com/v1/facebook/adLibrary/ad" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/adLibrary/ad/transcript

Ad Transcript Price: 5 credits. MCP tool: `facebook_adlibrary_ad_transcript`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | no | Facebook Ad Id |
| `url` | string | no | Facebook Ad URL |
| `cache_max_age` | string (1d, 3d, 7d, 14d, 30d) | no | If we have a response in the cache that is this many days old or newer, return the cached response (0 credits, with "cached": true and a "ca |

```bash
curl "https://scrapeio.com/v1/facebook/adLibrary/ad/transcript" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/adLibrary/company/ads

Company Ads Price: 5 credits. MCP tool: `facebook_adlibrary_company_ads`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `pageId` | string | no | The companies ad library page id. |
| `companyName` | string | no | The name of the company. |
| `country` | string | no | This can only be one country. |
| `status` | string (ALL, ACTIVE, INACTIVE) | no | Status of the ad. |
| `media_type` | string (ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE) | no | Media type of the ad. |
| `language` | string | no | Language to filter ads on. |
| `sort_by` | string (total_impressions, relevancy_monthly_grouped) | no | Sort by impressions (high to low), or Most Recent (relevancymonthlygrouped). |
| `start_date` | string | no | Start date to search for. |
| `end_date` | string | no | End date to search for. |
| `trim` | boolean | no | Set to true for a trimmed down version of the response |
| `cursor` | string | no | Cursor to paginate through results |

```bash
curl "https://scrapeio.com/v1/facebook/adLibrary/company/ads" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/adLibrary/search/ads

Search Price: 5 credits. MCP tool: `facebook_adlibrary_search_ads`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Keyword to search for |
| `sort_by` | string (total_impressions, relevancy_monthly_grouped) | no | Sort by impressions (high to low), or Most Recent (relevancymonthlygrouped). |
| `search_type` | string (keyword_unordered, keyword_exact_phrase) | no | If you want to search by exact phrase or not |
| `ad_type` | string (all, political_and_issue_ads) | no | Search for all ads or only political and issue ads |
| `country` | string | no | This can only be one country. |
| `language` | string | no | Language to filter ads on. |
| `status` | string (ALL, ACTIVE, INACTIVE) | no | Status of the ad. |
| `media_type` | string (ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME, NONE) | no | Media type of the ad. |
| `start_date` | string | no | Impressions start date. |
| `end_date` | string | no | Impressions end date. |
| `trim` | boolean | no | Set to true for a trimmed down version of the response |
| `cursor` | string | no | Cursor to paginate through results |

```bash
curl "https://scrapeio.com/v1/facebook/adLibrary/search/ads?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```

### GET /v1/facebook/adLibrary/search/companies

Search for Companies Price: 5 credits. MCP tool: `facebook_adlibrary_search_companies`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Keyword to search for |

```bash
curl "https://scrapeio.com/v1/facebook/adLibrary/search/companies?query=coffee" -H "x-api-key: $SCRAPEIO_API_KEY"
```