# Facebook — 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 ads running across Facebook, Instagram, Messenger, and Audience Network to analyze creative content, spending data, and political ad transparency information. Look up specific ads by keyword or page to get comprehensive details about active advertising campaigns.

**Category:** Social Media | **Website:** [www.facebook.com/ads/library/?active_status=active&ad_type=political_and_issue_ads&country=US&is_targeted_country=false&media_type=all&sort_data[mode]=total_impressions&sort_data[direction]=desc](https://www.facebook.com/ads/library/?active_status=active&ad_type=political_and_issue_ads&country=US&is_targeted_country=false&media_type=all&sort_data[mode]=total_impressions&sort_data[direction]=desc) | **Docs:** [parse.bot/marketplace/3c9b0980-36db-455f-bad4-1b89dac70b9e/facebook-com-api](https://parse.bot/marketplace/3c9b0980-36db-455f-bad4-1b89dac70b9e/facebook-com-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-api-3c9b0980/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_ad_details

Retrieve details for a specific ad by its Ad Library ID. Returns a single ad object with full creative content, platform distribution, spend and impression data (for political/issue ads), and funding entity disclosures.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ad_id` | string | Yes | The numeric Ad Library ID (e.g. '1869276447125570'). Obtain from search_ads or search_page_ads results. |
| `country` | string | No | ISO 2-letter country code for the ad library region. |

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

### search_ads

Search the Facebook Ad Library by keyword or advertiser name. Returns up to ~30 ads per request matching the query, sorted by total impressions descending. For political/issue ads, results include spend ranges, impression counts, and funding entity disclosures. Results are auto-iterated; pass limit to cap total items fetched.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `active_status` | string | No | Filter by ad active status. |
| `ad_type` | string | No | Category of ads to search. |
| `country` | string | No | ISO 2-letter country code for the ad library region (e.g. US, GB, DE, BR). |
| `forward_cursor` | string | No | Opaque cursor for fetching the next page of results. Obtain from the page_info.end_cursor field of a previous response. |
| `media_type` | string | No | Filter by media type. Accepted values: all, image, meme, video, none. |
| `query` | string | Yes | Keyword or advertiser name to search for in the Ad Library. |
| `search_type` | string | No | Type of search matching. Accepted values: keyword_unordered, keyword_exact_phrase. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-facebook-com-api-3c9b0980/search_ads \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"active_status":"<string>","ad_type":"<string>","country":"<string>","forward_cursor":"<string>","media_type":"<string>","query":"<string>","search_type":"<string>"}'
```

### search_page_ads

List all ads run by a specific Facebook page. Returns ads associated with the given page ID, with the same rich detail as search_ads. Useful for competitive analysis or monitoring a specific advertiser's activity.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `active_status` | string | No | Filter by ad active status. |
| `ad_type` | string | No | Category of ads to filter. |
| `country` | string | No | ISO 2-letter country code for the ad library region. |
| `forward_cursor` | string | No | Opaque cursor for fetching the next page of results. Obtain from the page_info.end_cursor field of a previous response. |
| `page_id` | string | Yes | The numeric Facebook page ID (e.g. '15087023444' for Nike). Obtain from search_ads results or the page's Facebook URL. |

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