# Meta Ad Library API

> Meta Ad Library returns ads and creative details as a workflow and API.

Meta Ad Library returns matching ads, including ad text, headlines, platforms, and creative links. Search ads requires an advertiser name or keywords and can filter by status, country, or creative format.

- Page: https://fous.com/tools/meta-ad-library
- Handle: `@meta-ad-library`
- Category: [Marketing](https://fous.com/tools/category/marketing)
- Source website: https://facebook.com/ads/library
- Last verified: Sep 28, 2026

## Methods

### Search ads

Operation `search_ads`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Find ads matching an advertiser or keywords in Meta Ad Library, in the library’s order. Some ads show multiple versions without a published version count.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `query` | string | yes | `"Nike"` | Advertiser name or keywords to search, for example Nike or meal kit. |
| `status` | string | no | `"active"` | Ad status to include, for example active. |
| `country` | string | no | `"United States"` | Country name or two-letter country code, for example United States or US; all searches every country. |
| `media_type` | string | no | `"all"` | Creative format, for example video. |
| `max_results` | integer | no | `5` | Maximum ads to return, for example 30. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Advertiser name or keywords to search, for example Nike or meal kit.",
      "examples": [
        "Nike",
        "meal kit",
        "zzzzqxyunlikelybrandnomatch000101"
      ]
    },
    "status": {
      "enum": [
        "active",
        "inactive",
        "all"
      ],
      "type": "string",
      "default": "active",
      "description": "Ad status to include, for example active.",
      "examples": [
        "active",
        "inactive"
      ]
    },
    "country": {
      "type": "string",
      "default": "United States",
      "description": "Country name or two-letter country code, for example United States or US; all searches every country.",
      "examples": [
        "United States",
        "US",
        "all"
      ]
    },
    "media_type": {
      "enum": [
        "all",
        "image",
        "video"
      ],
      "type": "string",
      "default": "all",
      "description": "Creative format, for example video.",
      "examples": [
        "all",
        "image",
        "video"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 30,
      "maximum": 200,
      "minimum": 1,
      "description": "Maximum ads to return, for example 30.",
      "x-fous-developer": true,
      "examples": [
        5,
        7,
        4
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "query": "Nike",
      "status": "active",
      "country": "United States",
      "media_type": "all",
      "max_results": 5
    },
    {
      "query": "meal kit",
      "status": "active",
      "country": "US",
      "media_type": "image",
      "max_results": 7
    },
    {
      "query": "Nike",
      "status": "inactive",
      "country": "all",
      "media_type": "video",
      "max_results": 5
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `ads` | array |  |  |
| `ads[].active` | boolean | `true` |  |
| `ads[].ad_text` | string or null | `"Buy online and pick up in store for free! Get up to 70% off Nike, Vince, Madewell, adidas and more."` |  |
| `ads[].headline` | string or null | `"Fast & Free Pickup"` |  |
| `ads[].platforms` | array |  |  |
| `ads[].image_links` | array |  |  |
| `ads[].video_links` | array |  |  |
| `ads[].library_ad_id` | string | `"925321173274919"` |  |
| `ads[].ad_library_link` | string | `"https://www.facebook.com/ads/library/?id=925321173274919"` |  |
| `ads[].advertiser_name` | string or null | `"Nordstrom Rack"` |  |
| `ads[].landing_page_link` | string or null | `"https://fb.com/canvas_doc/1072291375736811"` |  |
| `ads[].call_to_action_text` | string or null | `"Learn more"` |  |
| `ads[].advertiser_page_link` | string or null | `"https://www.facebook.com/NordstromRack/"` |  |
| `ads[].started_running_date` | string or null | `"2026-08-03"` | First day the ad ran, YYYY-MM-DD. |
| `ads[].number_of_ad_versions` | integer or null | `1` | Null when the library says there are multiple versions but does not show how many. |

**Example input**

```json
{
  "query": "Nike",
  "status": "active",
  "country": "United States",
  "media_type": "all",
  "max_results": 5
}
```

**Example output**

```json
{
  "ads": [
    {
      "active": true,
      "ad_text": "Buy online and pick up in store for free! Get up to 70% off Nike, Vince, Madewell, adidas and more.",
      "headline": "Fast & Free Pickup",
      "platforms": [
        "Facebook"
      ],
      "image_links": [],
      "video_links": [
        "https://video-phl2-1.xx.fbcdn.net/o1/v/t2/f2/m366/AQPMHFeiZ7eLWAaUSfl9UjSZ2QaJHkx2VTZvZtGQn2Lri3AqZsR0B4SYnzTlS8BwXd3tuMjYDH1B574OT7dthdkPDTun_TubomWQGGrRBkvZaQ.mp4?_nc_cat=104&_nc_sid=b66105&_nc_ht=v…"
      ],
      "library_ad_id": "925321173274919",
      "ad_library_link": "https://www.facebook.com/ads/library/?id=925321173274919",
      "advertiser_name": "Nordstrom Rack",
      "landing_page_link": "https://fb.com/canvas_doc/1072291375736811",
      "call_to_action_text": "Learn more",
      "advertiser_page_link": "https://www.facebook.com/NordstromRack/",
      "started_running_date": "2026-08-03",
      "number_of_ad_versions": 1
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@meta-ad-library",
  "visibility": "public",
  "operation": "search_ads",
  "version": 1,
  "input": {
    "query": "Nike",
    "status": "active",
    "country": "United States",
    "media_type": "all",
    "max_results": 5
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@meta-ad-library\",\n  \"visibility\": \"public\",\n  \"operation\": \"search_ads\",\n  \"version\": 1,\n  \"input\": {\n    \"query\": \"Nike\",\n    \"status\": \"active\",\n    \"country\": \"United States\",\n    \"media_type\": \"all\",\n    \"max_results\": 5\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@meta-ad-library",
  "visibility": "public",
  "operation": "search_ads",
  "version": 1,
  "input": {
    "query": "Nike",
    "status": "active",
    "country": "United States",
    "media_type": "all",
    "max_results": 5
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/meta-ad-library`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `search_ads`: Search ads. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-meta-ad-library https://api.fous.com/mcp/tools/meta-ad-library --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Compare ad creatives across advertisers
- Review ad text and headlines
- Find ads by country or creative format
- Check when ads started running
- Collect advertiser and landing page links

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Meta Ad Library tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Meta Ad Library account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from facebook.com when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 28, 2026.

### What ads match an advertiser or keywords?

Search ads finds matching ads and returns details such as ad text, headlines, and creative links.

### When did an ad start running?

Search ads returns the first day an ad ran when that date is available.

### Which platforms show an ad?

Search ads returns the platforms listed for each matching ad.

## Related

- [Google Ads Transparency Center API](https://fous.com/tools/google-ads-transparency-center.md): Explore public ads shown across Google services and sites.
- [Open Library API](https://fous.com/tools/open-library.md): Open Library returns book search results, catalog details, and author works; availability reflects listed editions, not current loan availability, and catalog details may be missing.
- [OverDrive API](https://fous.com/tools/overdrive.md): Find ebooks and audiobooks at public libraries.
- [Microsoft Store API](https://fous.com/tools/microsoft-store.md): Microsoft Store returns app and game listings, country-specific searches, and ranked charts; update notes, purchase prices, and exact rating counts may be unavailable.
- [Mercado Libre API](https://fous.com/tools/mercado-libre.md): Search public marketplace listings in Latin America.
- [Apple App Store API](https://fous.com/tools/apple-app-store.md): Apple App Store returns public app listings, keyword search, ratings, prices, listed purchases, country-specific reviews and visible replies, and up to 200 ranked chart apps.
- [Google Play API](https://fous.com/tools/google-play.md): Google Play helps people discover Android apps and games, view public listings and search results, read reviews when available by app and region, and see country-specific top charts.
- [Library of Congress API](https://fous.com/tools/library-of-congress.md): Library of Congress returns searchable digital collections and historic newspaper pages; rights notes may be absent, and newspaper text may contain OCR errors.
- [All Marketing tools](https://fous.com/tools/category/marketing)