Name: Meta Ad Library API: Facebook and Instagram Ads
Brand: s-r
SKU: api-s-r-meta-ads-library
Availability: InStock
Author: API Market

# Meta Ad Library API

## Overview

The Meta Ad Library API returns the ads an advertiser runs on Facebook and Instagram, taken from Meta's public Ad Library, as clean JSON. You look an advertiser up by page name, page ID or an Ad Library URL, pick a country, and get each ad's text, images and videos, call to action, landing page, run dates, platforms and flags for AI-generated or sensitive content. The same search is available as a GET with query parameters and as a POST with a JSON body, and large result sets page with a cursor.

It is built for marketers, agencies, growth teams and ad-intelligence tools that track competitors' creative and messaging. Every ad comes with the advertiser's page details, such as name, categories and follower count, so you can build swipe files, monitor launches or study how a brand's ads change over time.

## Features

*   **2 endpoints**: the same search as `GET /run` with query parameters or `POST /run` with a JSON body.
*   **Find an advertiser 3 ways**: by page name, page ID or a pasted Ad Library URL.
*   **Full creative**: ad text, title, images, videos, call to action and landing page for every ad.
*   **Run dates and platforms**: start and end dates, active status, and Facebook or Instagram placement.
*   **Content flags**: whether the ad contains AI-generated media or sensitive content.
*   **Country filter**: any two-letter country code, US by default.
*   **Pagination**: up to 5000 ads per request, with `next_cursor` to continue.
*   **Rate limit**: 10 requests per second on Free and Basic, 20 on Pro, 50 on Plus.

## Use Cases

*   **Competitor monitoring**: track which ads a rival brand is running right now and when new ones launch.
*   **Creative research**: collect ad copy, images and calls to action into a swipe file.
*   **Agency reporting**: show clients what their competitors run on Facebook and Instagram in each country.
*   **Ad-intelligence tools**: feed active ads and run dates into dashboards or alerts.

## API Documentation

### Base URL

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

```
https://prod.api.market/api/v1/s-r/meta-ads-library
```

### Authentication

Every request must include 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 ads (query parameters)

Returns the ads of the advertiser you look up, with the total count and a cursor for the next page. Pass at least one of `search`, `page_id` or `url`.

**Method:** `GET`

**Endpoint:** `/run`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| search | query | Advertiser page name, such as `nike` | string | No | - | - |
| page_id | query | Facebook advertiser page ID, digits only. Takes precedence over `search` | string | No | - | - |
| url | query | A Meta Ad Library URL copied from the browser. `page_id` and `search` take precedence over it | string | No | - | - |
| country | query | Two-letter country code | string | No | US | - |
| active_only | query | Return active ads only | boolean | No | true | - |
| max_ads | query | Maximum number of ads to return | integer | No | 100 | 5000 |
| cursor | query | The `next_cursor` from a previous response, to get the next page. Keep the other filters unchanged | string | No | - | - |

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/s-r/meta-ads-library/run?search=nike&country=US&max_ads=3' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "data": {
    "items": [
      {
        "ad_id": "1016451784037642",
        "collation_count": null,
        "is_active": true,
        "page_id": "15087023444",
        "page_name": "Nike",
        "start_date": "2025-06-20",
        "end_date": "2025-08-28",
        "total_active_time": null,
        "publisher_platform": [
          "FACEBOOK"
        ],
        "reach_estimate": null,
        "currency": "",
        "spend": null,
        "targeted_or_reached_countries": [],
        "categories": [
          "UNKNOWN"
        ],
        "collation_id": null,
        "contains_digital_created_media": false,
        "contains_sensitive_content": false,
        "state_media_run_label": null,
        "page_is_deleted": false,
        "byline": null,
        "disclaimer_label": null,
        "page_profile_uri": "https://facebook.com/nike",
        "country_iso_code": null,
        "display_format": "DPA",
        "title": "{{product.name}}",
        "link_url": "https://www.nike.com/us/en_us",
        "link_description": null,
        "caption": "NIKE.COM",
        "cta_text": "Shop now",
        "cta_type": "SHOP_NOW",
        "page_profile_picture_url": "https://scontent-bos5-1.xx.fbcdn.net/v/t39.35426-6/509357337_4088170881445143_8138324132275675252_n.jpg?stp=dst-jpg_s60x...",
        "branded_content": null,
        "body_text": "Get the gear that goes hard on and off the field.",
        "page_like_count": 39488805,
        "page_categories": [
          "Sportswear"
        ],
        "images": [
          "https://scontent-bos5-1.xx.fbcdn.net/v/t39.35426-6/509290535_730168202720612_5631758797674183318_n.jpg?_nc_cat=109&ccb=1..."
        ],
        "videos": [],
        "impressions_text": null,
        "impressions_index": -1,
        "spend_text": null,
        "spend_index": null,
        "query": "nike",
        "country": "US",
        "resolved_page_id": "15087023444",
        "source": "meta-ads-library",
        "platform": "meta",
        "fetched_at": "2026-11-04T19:34:07.050Z",
        "advertiser_name": "Nike",
        "advertiser_id": "15087023444",
        "creative_id": "1016451784037642",
        "format": "DPA",
        "text": "Get the gear that goes hard on and off the field.",
        "landing_url": "https://www.nike.com/us/en_us",
        "first_seen": "2025-06-20",
        "last_seen": "2025-08-28",
        "region": "US",
        "image_url": "https://scontent-bos5-1.xx.fbcdn.net/v/t39.35426-6/509290535_730168202720612_5631758797674183318_n.jpg?_nc_cat=109&ccb=1..."
      }
    ],
    "total_count": 119,
    "next_cursor": "eyJ2ZXJzaW9uIjoxLCJwYWdlX2lkIjoiMTUwODcwMjM0NDQiLCJjb3VudHJ5IjoiVVMiLCJhY3RpdmVfb25seSI6dHJ1ZSwic2VhcmNoIjoibmlrZSIsInVw...",
    "partial": true,
    "warnings": [
      "Returned 3 ads; more ads are available via next_cursor."
    ]
  },
  "meta": {
    "request_id": "1d99c0b5-e47a-4930-b8f3-4255039553ee",
    "duration_ms": 4477,
    "units": 3,
    "cached": false
  }
}
```

#### 2. Search ads (JSON body)

The same search as the GET endpoint, with the parameters sent as a JSON body.

**Method:** `POST`

**Endpoint:** `/run`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| search | body | Advertiser page name, such as `nike` | string | No | - | - |
| page_id | body | Facebook advertiser page ID, digits only. Takes precedence over `search` | string | No | - | - |
| url | body | A Meta Ad Library URL copied from the browser. `page_id` and `search` take precedence over it | string | No | - | - |
| country | body | Two-letter country code | string | No | US | - |
| active_only | body | Return active ads only | boolean | No | true | - |
| max_ads | body | Maximum number of ads to return | integer | No | 100 | 5000 |
| cursor | body | The `next_cursor` from a previous response, to get the next page. Keep the other filters unchanged | string | No | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/s-r/meta-ads-library/run' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "search": "coolblue",
  "country": "NL",
  "max_ads": 3
}'
```

**Example Response (200 OK):**

```json
{
  "data": {
    "items": [
      {
        "ad_id": "2472373056568246",
        "collation_count": null,
        "is_active": true,
        "page_id": "422603325536",
        "page_name": "Coolblue",
        "start_date": "2026-06-25",
        "end_date": "2026-11-04",
        "total_active_time": null,
        "publisher_platform": [
          "FACEBOOK"
        ],
        "reach_estimate": null,
        "currency": "",
        "spend": null,
        "targeted_or_reached_countries": [],
        "categories": [
          "EMPLOYMENT"
        ],
        "collation_id": null,
        "contains_digital_created_media": false,
        "contains_sensitive_content": false,
        "state_media_run_label": null,
        "page_is_deleted": false,
        "byline": null,
        "disclaimer_label": null,
        "page_profile_uri": "https://facebook.com/Coolblue",
        "country_iso_code": null,
        "display_format": "DPA",
        "title": "{{product.name}}",
        "link_url": "https://www.careersatcoolblue.com/",
        "link_description": "{{product.description}}",
        "caption": "careersatcoolblue.com",
        "cta_text": "Apply now",
        "cta_type": "APPLY_NOW",
        "page_profile_picture_url": "https://scontent-ams2-1.xx.fbcdn.net/v/t39.35426-6/731834882_963104756723892_862714434917884101_n.jpg?stp=dst-jpg_s60x60...",
        "branded_content": null,
        "body_text": "{{product.custom_label_2}}",
        "page_like_count": 455151,
        "page_categories": [
          "Retail company"
        ],
        "images": [
          "https://scontent-ams2-1.xx.fbcdn.net/v/t39.35426-6/732011507_1316961253496772_5528601961799641260_n.jpg?_nc_cat=109&ccb=..."
        ],
        "videos": [],
        "impressions_text": null,
        "impressions_index": -1,
        "spend_text": null,
        "spend_index": null,
        "query": "coolblue",
        "country": "NL",
        "resolved_page_id": "422603325536",
        "source": "meta-ads-library",
        "platform": "meta",
        "fetched_at": "2026-11-04T19:34:12.178Z",
        "advertiser_name": "Coolblue",
        "advertiser_id": "422603325536",
        "creative_id": "2472373056568246",
        "format": "DPA",
        "text": "{{product.custom_label_2}}",
        "landing_url": "https://www.careersatcoolblue.com/",
        "first_seen": "2026-06-25",
        "last_seen": "2026-11-04",
        "region": "NL",
        "image_url": "https://scontent-ams2-1.xx.fbcdn.net/v/t39.35426-6/732011507_1316961253496772_5528601961799641260_n.jpg?_nc_cat=109&ccb=..."
      }
    ],
    "total_count": 151,
    "next_cursor": "eyJ2ZXJzaW9uIjoxLCJwYWdlX2lkIjoiNDIyNjAzMzI1NTM2IiwiY291bnRyeSI6Ik5MIiwiYWN0aXZlX29ubHkiOnRydWUsInNlYXJjaCI6ImNvb2xibHVl...",
    "partial": true,
    "warnings": [
      "Returned 3 ads; more ads are available via next_cursor."
    ]
  },
  "meta": {
    "request_id": "7a0c6807-55a1-40a6-81a4-7b19d2050581",
    "duration_ms": 3800,
    "units": 3,
    "cached": false
  }
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | The path does not exist, or the resource you asked for was not found. |
| 429 | Too Many Requests | You sent more than your plan's requests per second (10 on Free and Basic, 20 on Pro, 50 on Plus). Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

The Free and Basic plans allow up to 10 requests per second, Pro allows 20 and Plus allows 50. Each plan also has a monthly call quota shown on the pricing page. Going over your plan's per-second limit returns `429 Too Many Requests`. Throttle your client to stay under it, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **Should I use GET or POST?**

    Both run the same search and return the same response. Use GET for quick calls and POST when you prefer a JSON body.

*   **How do I get more ads?**

    Each response includes `total_count` and `next_cursor`. Send `next_cursor` back as `cursor` with the same filters to get the next page.

*   **What if search, page_id and url are all set?**

    `page_id` is used first, then `search`, then the URL. A country inside the URL takes precedence over `country`.

*   **Why do some ads show text like {{product.name}}?**

    These are dynamic product ads, where Meta fills the text from the advertiser's product catalog when it shows the ad. The Ad Library publishes the template, so the API returns it as is.

*   **Why are spend and reach often null?**

    Meta publishes spend and reach only for some ads, such as political and issue ads, so for most commercial ads these fields are null.

## 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.


Search Facebook and Instagram ads from the Meta Ad Library by advertiser, page ID or URL and get creatives, run dates and platforms as JSON.