# Facebook — 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 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/facebook/`
**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 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.beta.paywithlocus.com/api/wrapped/credits/facebook/get-ad-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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.beta.paywithlocus.com/api/wrapped/credits/facebook/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>","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.beta.paywithlocus.com/api/wrapped/credits/facebook/search-page-ads \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"active_status":"<string>","ad_type":"<string>","country":"<string>","forward_cursor":"<string>","page_id":"<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.