# Facebook Ad Library — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and retrieve detailed information about ads running on Facebook, including creative content, audience targeting parameters, and transparency metrics. Access comprehensive ad data across multiple campaigns to monitor advertising trends and competitive activity.

**Category:** Social Media | **Website:** [de-de.facebook.com/ads/library/?active_status=all&ad_type=all&country=AT&is_targeted_country=false&media_type=all&search_type=page&sort_data%5Bdirection%5D=desc&sort_data%5Bmode%5D=total_impressions&view_all_page_id=2214120985581210](https://de-de.facebook.com/ads/library/?active_status=all&ad_type=all&country=AT&is_targeted_country=false&media_type=all&search_type=page&sort_data%5Bdirection%5D=desc&sort_data%5Bmode%5D=total_impressions&view_all_page_id=2214120985581210) | **Docs:** [parse.bot/marketplace/c0bf395f-27fe-4c8d-ad3f-4b51eb2092cc/facebook-com-ad-library-api](https://parse.bot/marketplace/c0bf395f-27fe-4c8d-ad3f-4b51eb2092cc/facebook-com-ad-library-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-facebook-com-ad-library-api-c0bf395f/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_ad_collation

Get all ad versions within a collation group (ads that Facebook groups together as similar/related). Returns full ad data for each version in the group. Supports cursor-based pagination via forward_cursor.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `active_status` | string | No | Filter by active status: 'ALL', 'ACTIVE', 'INACTIVE'. |
| `ad_type` | string | No | Filter by ad type: 'ALL', 'POLITICAL_AND_ISSUE_ADS'. |
| `collation_id` | string | Yes | The collation group ID (from search_ads results, field 'collation_id'). |
| `country` | string | No | ISO country code for the ad library context (e.g., 'AT', 'DE', 'HK', 'US'). |
| `forward_cursor` | string | No | Pagination cursor from a previous response's forward_cursor field. Omit or empty string for first page. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-facebook-com-ad-library-api-c0bf395f/get_ad_collation \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active_status":"<string>","ad_type":"<string>","collation_id":"<string>","country":"<string>","forward_cursor":"<string>"}'
```

### get_ad_details

Get detailed information about a specific ad including advertiser info, EU transparency data with audience targeting breakdowns, payer/beneficiary information, and violation status.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ad_archive_id` | string | Yes | The ad archive ID (from search_ads results, field 'ad_archive_id'). |
| `country` | string | No | ISO country code for the ad library context (e.g., 'AT', 'DE', 'HK', 'US'). |
| `page_id` | string | Yes | The page ID of the advertiser (from search_ads results, field 'page_id'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-facebook-com-ad-library-api-c0bf395f/get_ad_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ad_archive_id":"<string>","country":"<string>","page_id":"<string>"}'
```

### search_ads

Search Facebook Ad Library for ads by page ID or search term. Returns ads with their creative content, dates, platforms, and metadata. Supports cursor-based pagination via after_cursor. At least one of page_id or search_term must be provided.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `active_status` | string | No | Filter by active status: 'all', 'active', 'inactive'. |
| `ad_type` | string | No | Filter by ad type: 'all', 'political_and_issue_ads'. |
| `after_cursor` | string | No | Pagination cursor from a previous response's end_cursor field. Omit or empty string for first page. |
| `country` | string | No | ISO country code to filter ads (e.g., 'AT', 'DE', 'HK', 'US'). |
| `media_type` | string | No | Filter by media type: 'all', 'image', 'meme', 'video', 'none'. |
| `page_id` | string | No | Facebook page ID to get all ads for (e.g., '2214120985581210'). Either page_id or search_term must be provided. |
| `search_term` | string | No | Keyword to search ads for. Either page_id or search_term must be provided. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-facebook-com-ad-library-api-c0bf395f/search_ads \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active_status":"<string>","ad_type":"<string>","after_cursor":"<string>","country":"<string>","media_type":"<string>","page_id":"<string>","search_term":"<string>"}'
```