# Facebook Ad Library — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/facebook-ad-library/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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.beta.paywithlocus.com/api/wrapped/credits/facebook-ad-library/get-ad-collation \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/facebook-ad-library/get-ad-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/facebook-ad-library/search-ads \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.