Name: Meta Ad Library API for Facebook and Instagram Ads
Brand: unseen-user
SKU: api-unseen-user-meta-ad-library-api
Availability: InStock
Author: API Market

Unseen User

# Meta Ad Library API

## Overview

The Meta Ad Library API searches the public Meta Ad Library and returns Facebook and Instagram ads as structured JSON. One endpoint covers four jobs, chosen with `searchMode`: find ads by keyword, get all ads from a brand or Facebook page, look up a brand's Facebook page ID, and get full details for a single ad. Each request runs a live scrape of the Ad Library at call time, so results reflect what Meta is publishing at that moment, across Facebook, Instagram, Messenger, Audience Network and Threads placements. No Facebook account, cookies, Meta developer app or access token is needed.

It is built for marketers, agencies, e-commerce teams, researchers and journalists who want competitor and category ad data in their own database, spreadsheet or AI agent. Each row in `data` is one ad with its Ad Library ID, page name and ID, active status, start and end dates, placements, and a `snapshot` that holds the ad copy, title, call to action, landing URL, display format and media links (images, videos and cards). Optional switches add creative analysis fields, advertiser and landing page summary rows, separate tables, video transcripts and AI tagging. Political and issue ads carry the spend and impression ranges Meta publishes for them.

## Features

*   **1 endpoint, 4 modes**: Keyword ad search, all ads from a brand or page, brand to page ID lookup, and full details for one ad, all through `POST /v1/meta-ads`.
*   **Flexible inputs**: Send keywords, brand names, numeric Facebook page IDs, ad IDs or full Ad Library URLs in `searchTerms`. Brand names are resolved to page IDs automatically.
*   **Live scrape of the public Ad Library**: Every request collects data at call time. No login, cookies or proxy settings are involved.
*   **Filters**: Country, ad status, date range, media type, keyword match type, sort order, language and political or issue ads only.
*   **Volume controls**: Cap results with `maxItems`, `maxItemsPerTerm` and `maxPagesPerQuery`. One call returns up to 100 rows.
*   **Creative analysis**: Set `enrichment` to split Dynamic Creative ads into their variants, list all media in one place, extract the landing domain, count days running and detect the copy language.
*   **Summary rows and tables**: Add one row per advertiser or per landing page, or get separate creative, landing page and advertiser tables in `extras`.
*   **Rate limit**: 2 requests per second on every plan.

## Use Cases

*   **Competitor ad research**: See every ad a competitor is running, with copy, creative, call to action and landing URL.
*   **Creative briefs and swipe files**: Pull ad formats and copy as JSON for creative teams, or feed them into a sheet or database on a schedule.
*   **Testing analysis**: Use `creative.variants[]` to see the headline, copy and button combinations a brand is testing in Dynamic Creative ads.
*   **Political ad research**: Track spend ranges, impression ranges and reach estimates on political and issue ads.
*   **Brand-safety monitoring**: Search your brand name or trademarks to find unauthorized or counterfeit ads.
*   **Influencer and partner checks**: Confirm whether a claimed brand partnership has ads running.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/unseen-user/meta-ad-library-api
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Search the Meta Ad Library

Runs a Meta Ad Library search in the mode you choose and returns the matching ads (or page records, in page ID lookup mode) as rows in `data`. The response always has the shape `{ "success": true, "data": [...], "meta": {...}, "extras": {...} }`, where `meta` carries the count and run information and `extras` carries the optional separate tables. In our test, a 5-ad keyword search returned in about 10 seconds.

The four values of `searchMode` change what `searchTerms` means:

*   **`search_ads`**: Keywords, for example `running shoes`.
*   **`company_ads`**: Brand names (for example `Nike`) or numeric Facebook page IDs (for example `15087023444`).
*   **`search_companies`**: Brand names. Returns page name, category, likes, verification status and Instagram handle and followers.
*   **`ad_details`**: Ad IDs (for example `702369045530963`) or full Ad Library URLs. Returns every creative variant, link URL, call to action and, for EU-targeted ads, the `aaa_info` audience breakdown by age, country and gender.

**Method:** `POST`

**Endpoint:** `/v1/meta-ads`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `searchMode` | body | What to do: `search_ads`, `company_ads`, `search_companies` or `ad_details`. | string | Yes | `search_ads` | - |
| `searchTerms` | body | Keywords, brand names, page IDs or ad IDs, depending on `searchMode`. Each term runs its own search. | array of strings | Yes | - | - |
| `countries` | body | Two-letter country codes such as `US`, `GB` or `DE`, or `ALL` for worldwide. With several countries, the search runs once per country and the results are merged; an ad found in more than one country is returned once. Applies to `search_ads` and `company_ads`. | array of strings | No | `["ALL"]` | - |
| `status` | body | `ACTIVE` for running ads only, `INACTIVE` for ended ads, or `ALL`. Applies to `search_ads` and `company_ads`. | string | No | `ACTIVE` | - |
| `startDate` | body | Only include ads running on or after this date, for example `2026-01-01`. Applies to `search_ads` and `company_ads`. | string | No | - | - |
| `endDate` | body | Only include ads running on or before this date. Applies to `search_ads` and `company_ads`. | string | No | - | - |
| `mediaType` | body | Creative format filter: `ALL`, `IMAGE`, `VIDEO`, `MEME`, `IMAGE_AND_MEME` or `NONE`. Applies to `search_ads` and `company_ads`. | string | No | `ALL` | - |
| `searchType` | body | Keyword match: `keyword_unordered` or `keyword_exact_phrase`. Applies to `search_ads` only. | string | No | `keyword_unordered` | - |
| `sortBy` | body | Sort order: `total_impressions` or `relevancy_monthly_grouped`. Applies to `search_ads` and `company_ads`. | string | No | `total_impressions` | - |
| `languages` | body | Uppercase two-letter language codes such as `EN`, `ES` or `DE`. Each language runs its own search. Leave empty for no language filter. Applies to `company_ads`. | array of strings | No | `[]` | - |
| `adType` | body | `all`, or `political_and_issue_ads` to return only political and issue ads, which carry spend and impression ranges. Applies to `search_ads`. | string | No | `all` | - |
| `maxItems` | body | Total ads to collect across all search terms; `0` means all ads found. The budget is split evenly across terms. | integer | No | `0` | 100 rows per call |
| `maxItemsPerTerm` | body | Cap per search term; `0` means no per-term limit. Applies to `search_ads` and `company_ads`. | integer | No | `0` | - |
| `maxPagesPerQuery` | body | Maximum result pages fetched per search term; `0` means all pages. Applies to `search_ads` and `company_ads`. | integer | No | `0` | - |
| `enrichment` | body | Adds creative analysis fields to every ad: `creative.variants`, `creative.media`, `creative.partner`, `landing.domain`, `signals.days_running` and `enrichment.language`. Built from data already in the response. | boolean | No | `false` | - |
| `longRunningDays` | body | Ads live for at least this many days get `signals.long_running: true`. Used only when `enrichment` is on. | integer | No | `30` | - |
| `advertiserProfiles` | body | Adds one summary row per advertiser: ad count, active ad count, longest running days, first and last seen, landing domains, distinct copy count, platforms, formats and page and Instagram follower data. Needs `enrichment`. Each summary row counts as a result. | boolean | No | `false` | - |
| `landingPageReport` | body | Adds one row per distinct destination URL with the number of ads using it, the advertisers, UTM parameters and the final resolved URL. Needs `enrichment`. | boolean | No | `false` | - |
| `separateTables` | body | Also returns creative, landing page and advertiser tables in `extras`, next to `data`. Needs `enrichment`. | boolean | No | `false` | - |
| `getTranscript` | body | Includes a video transcript. Applies to `ad_details` and works on videos under 2 minutes. | boolean | No | `false` | - |
| `trim` | body | Strips rarely used fields from each ad for a smaller response. | boolean | No | `false` | - |
| `anthropicApiKey` | body | Your own Anthropic API key. Needed only for `llmAnalysis` or `strategySummary`; that usage is billed to your Anthropic account. Never returned in the output. | string | No | - | - |
| `llmAnalysis` | body | Tags each ad's copy with `llm.primary_angle`, `llm.angles` and `llm.tone`. Angles: `offer`, `social_proof`, `authority`, `fear`, `curiosity`, `urgency`, `problem_solution`, `testimonial`, `comparison`, `aspirational`, `educational`. Needs `anthropicApiKey`. Applies to `search_ads` and `company_ads`. | boolean | No | `false` | - |
| `strategySummary` | body | Adds one strategy summary row per advertiser (positioning, target audience, creative strategy, dominant angles). Runs only when at least 10 ads were collected for that advertiser. Needs `anthropicApiKey`. Applies to `company_ads`. | boolean | No | `false` | - |
| `llmModel` | body | Model used for the AI options: `claude-opus-5`, `claude-sonnet-5` or `claude-haiku-4-5`. | string | No | `claude-opus-5` | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/unseen-user/meta-ad-library-api/v1/meta-ads" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"searchMode":"search_ads","searchTerms":["nike"],"countries":["ALL"],"status":"ACTIVE","mediaType":"ALL","searchType":"keyword_unordered","sortBy":"total_impressions","adType":"all","maxItems":5,"maxItemsPerTerm":5,"maxPagesPerQuery":1,"longRunningDays":30,"advertiserProfiles":false,"landingPageReport":false,"separateTables":false,"llmModel":"claude-opus-5"}'
```

**Example Response (200 OK, abridged to the first ad and its first card):**

```json
{
  "success": true,
  "data": [
    {
      "ad_archive_id": "1702938977100376",
      "is_active": true,
      "page_id": "15087023444",
      "page_is_deleted": false,
      "snapshot": {
        "page_id": "15087023444",
        "page_is_deleted": false,
        "page_profile_uri": "https://www.facebook.com/nike/",
        "page_name": "Nike",
        "page_profile_picture_url": "https://scontent-lga3-3.xx.fbcdn.net/v/t39.35426-6/431756959_712871054375981_2401799800446082357_n.jpg?stp=dst-jpg_s60x60_tt6&_nc_cat=104&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=tYHDxrNM0v0Q7kNvwF83D3k&_nc_oc=AdrUdAhn723LAR-U_sYiJnCnhg_Lxp5mflzg9i1nZkgLAcjLg6mLMTe4HnqbLSHltzQ&_nc_zt=14&_nc_ht=scontent-lga3-3.xx&_nc_gid=3EOo8fRrOVarwqSLYwydDA&_nc_ss=78289&oh=00_AQMHYuI3kPCgGZcJxC17uhDy0vtFZpos0O3y97sExLo0Ug&oe=6AD73806",
        "caption": "itunes.apple.com",
        "cta_text": "Install now",
        "cards": [
          {
            "body": "Bring sports more fully into your day with the Nike App.",
            "cta_type": "INSTALL_MOBILE_APP",
            "caption": "itunes.apple.com",
            "link_description": "₱3,995",
            "link_url": "https://www.nike.com/ph/t/run-swift-3-road-running-shoes-2fHbzp/DR2698-002",
            "title": "Nike Run Swift 3 Women's Road Running Shoes",
            "cta_text": "Install Now",
            "original_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/431679131_949214166636263_7090981238489979310_n.jpg?_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DXY20Vj2aQ8Q7kNvwFrOYZk&_nc_oc=AdpQk1ApRkV4xdMXLjSOiWrH5LlxXQN-yatgbfa9o8-iVAcrTtBOaWsJXwQtLESS2Zw&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=3EOo8fRrOVarwqSLYwydDA&_nc_ss=78289&oh=00_AQNfPJSv5J9oGHX14GWdYpVUEMM9oKxd2lYBsHQQ51hs0g&oe=6AD71311",
            "resized_image_url": "https://scontent-lga3-2.xx.fbcdn.net/v/t39.35426-6/431679131_949214166636263_7090981238489979310_n.jpg?stp=dst-jpg_s600x600_tt6&_nc_cat=100&ccb=1-7&_nc_sid=c53f8f&_nc_ohc=DXY20Vj2aQ8Q7kNvwFrOYZk&_nc_oc=AdpQk1ApRkV4xdMXLjSOiWrH5LlxXQN-yatgbfa9o8-iVAcrTtBOaWsJXwQtLESS2Zw&_nc_zt=14&_nc_ht=scontent-lga3-2.xx&_nc_gid=3EOo8fRrOVarwqSLYwydDA&_nc_ss=78289&oh=00_AQOCMMcVQ56rWixqlDd8ZJfc2aqxB1NYEonedIiHbIkFpw&oe=6AD71311"
          }
        ]
      }
    }
  ]
}
```

**Main fields in each ad row:**

*   **Identity**: `ad_archive_id`, `page_id`, `page_name`, `url` (the ad's Ad Library link).
*   **Status and timing**: `is_active`, `start_date`, `end_date`, `start_date_string`, `end_date_string`.
*   **Placement**: `publisher_platform`, listing every Meta surface the ad runs on.
*   **Creative**: `snapshot.display_format` (for example `IMAGE`, `VIDEO`, `MULTI_IMAGES`, `DCO`, `DPA`), `snapshot.title`, `snapshot.body.text`, `snapshot.caption`, `snapshot.link_description`.
*   **Call to action**: `snapshot.cta_text`, `snapshot.cta_type`, `snapshot.link_url`.
*   **Media**: `snapshot.images[]`, `snapshot.videos[]` (HD, SD and preview URLs) and `snapshot.cards[]` for carousel, Dynamic Creative and product ads.
*   **Grouping**: `collation_id` and `collation_count` group variants of the same ad.
*   **Political and issue ads**: `spend`, `currency`, `impressions_with_index` and `reach_estimate`, published by Meta as ranges.

Null values, empty strings and empty arrays are removed from the output.

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The search ran and the rows are in `data`. If nothing matched, the response explains the likely cause instead of returning nothing. |
| 400 | Bad Request | The body is invalid: `searchMode` or `searchTerms` is missing, or a field has a value outside its allowed options. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The endpoint path is wrong. Use `POST /v1/meta-ads`. |
| 429 | Too Many Requests | You went over 2 requests per second, or you used up your plan's request quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | The scrape could not be completed. Retry the request. |
| 503 | Service Unavailable | The service is busy or temporarily unavailable. Retry shortly. |
| 504 | Gateway Timeout | The scrape took too long. Calls stop after about 150 seconds; ask for fewer items and try again. |

## Rate Limits

The Free, Basic, Pro, Ultra and Mega plans all allow 2 requests per second. The Free plan includes 25 requests and stops there; upgrade to a paid plan to keep going. Each request runs a live scrape that took about 10 seconds in our test, so send requests in sequence or with low concurrency. Requests above the limit return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header.

## FAQ

**Do I need a Facebook account, cookies or a Meta developer app?**

No. The API reads the public Meta Ad Library. You do not need a Facebook login, browser cookies, a Business Manager, an app review or an access token. Your API.market key is the only credential.

**Does it return ad spend and impressions?**

Only for political and issue ads, because Meta does not publish spend or impressions for commercial ads. Set `adType` to `political_and_issue_ads` to get `spend`, `currency`, `impressions_with_index` and `reach_estimate`. These are ranges such as `$350K - $400K` and `>1M`, not exact figures. EU audience breakdowns by age, country and gender come from `ad_details` mode in the `aaa_info` field.

**How many ads can I get?**

One call returns up to 100 rows. The Ad Library itself stops paginating at roughly 1,500 results for one keyword. For wider coverage, split a broad search by keyword, country or date range, or search by brand with `company_ads`.

**How do I find a competitor's longest-running ads?**

Use `company_ads` with the brand name, set `enrichment` to `true` and sort the rows by `signals.days_running`. Ads past the `longRunningDays` threshold get `signals.long_running: true`. Meta publishes no performance data for commercial ads, so run time is the closest available signal.

**Why do some image and video links stop working?**

Media URLs point at Meta's CDN and expire after a while. Download any creative you want to keep instead of storing the URL.

**What do the AI options need?**

`llmAnalysis` and `strategySummary` need your own Anthropic API key in `anthropicApiKey`, and that usage is billed to your Anthropic account. If an AI request fails, the ad is still returned, just without tags.

**Can I get every version of a Dynamic Creative ad?**

Yes. Set `enrichment` to `true` and each alternative appears in `creative.variants[]` with its own title, body, button, destination and media.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Meta Ad Library API that returns Facebook and Instagram ads by keyword, brand or ad ID, with ad copy, CTAs, landing URLs, media links and run dates.

Meta Ad Library API for Facebook and Instagram Ads

Free