# Facebook Ad Library Search

Search ads that Meta publishes in its ad transparency library. Supply a query for keyword search, or a page_id to search one advertiser, optionally using either or both. Returns creative text, call-to-action, destination links, media URLs, advertiser identity, delivery dates, active status and publishing platform for up to 10 ads per request, plus a cursor for the next page. A single request covers one upstream lookup and costs one credit. The library has no sorting option: the public surface rejects every published sort mode, so ads are returned in the library's own order. spend and impressions are often absent for individual ads and are returned as null rather than estimated. Reach is reported only as a coarse display bucket.

- **Documentation:** [https://scrappa.co/docs/facebook-ad-library-api/meta_ad_library_search](https://scrappa.co/docs/facebook-ad-library-api/meta_ad_library_search)
- **API group:** Facebook Ad Library API
- **Endpoint:** `GET https://scrappa.co/api/facebook-ad-library/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | No | Keyword to search for in public ads. |
| `page_id` | string | No | Numeric advertiser page id to search a single advertiser. Obtain it from the advertisers endpoint. |
| `country` | string | No | Two-letter ISO country code to restrict the search to. |
| `ad_type` | string | No | Ad category to filter by: ALL, POLITICAL_AND_ISSUE_ADS, CREDIT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, EMPLOYMENT_ADS, HOUSING_ADS or UNCATEGORIZED_ADS. |
| `media_type` | string | No | Creative format to filter by: ALL, IMAGE, MEME, IMAGE_AND_MEME, VIDEO or NONE. |
| `active_status` | string | No | Restrict to currently running ads (ACTIVE), stopped ads (INACTIVE) or both (ALL). |
| `publisher_platforms` | array | No | Restrict to ads placed on given platforms, such as facebook, instagram or audience_network. Pass the parameter more than once to allow several platforms. |
| `start_date` | integer | No | Only return ads whose delivery started at or after this Unix timestamp in seconds. |
| `cursor` | string | No | Pagination cursor taken from the previous response. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/facebook-ad-library/search?query=climate&country=US&ad_type=POLITICAL_AND_ISSUE_ADS"
```

## Example response

```json
{
    "search_parameters": {
        "engine": "facebook_ad_library",
        "query": "climate",
        "page_id": null,
        "country": "US",
        "ad_type": "POLITICAL_AND_ISSUE_ADS",
        "media_type": null,
        "active_status": null,
        "start_date": null,
        "publisher_platforms": null,
        "cursor": null
    },
    "ads": [
        {
            "ad_archive_id": "558896812037021",
            "page_id": "15087023444",
            "page_name": "Example Advertiser",
            "page_profile_uri": "https://www.facebook.com/example",
            "page_like_count": 12000,
            "page_categories": [
                "Government"
            ],
            "publisher_platform": "facebook",
            "publisher_platforms": [
                "facebook",
                "instagram"
            ],
            "is_active": false,
            "ad_delivery_start_time": "2023-05-04T00:00:00+00:00",
            "ad_delivery_stop_time": "2023-06-01T00:00:00+00:00",
            "text": "Example political advertising creative text.",
            "title": null,
            "caption": null,
            "cta_text": "Learn more",
            "cta_type": "LEARN_MORE",
            "link_url": "https://example.com",
            "display_format": "single_image",
            "images": [
                "https://example.com/image.jpg"
            ],
            "videos": [],
            "cards": [],
            "spend": null,
            "impressions_with_index": null,
            "reach_estimate": ">1M",
            "reach_estimate_bucket": ">1M",
            "reach_estimate_is_coarse_bucket": true,
            "platform_delivery": []
        }
    ],
    "ads_count": 1,
    "pagination": {
        "next_cursor": "CURSOR_FROM_RESPONSE",
        "has_more": true
    },
    "response_time_ms": 1200
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 503 | Ad library temporarily unavailable | The public ad library could not be reached. The request is not billed. |
| 422 | Unsupported filter value | One of the filter values is outside the published set. No upstream request is made and no credits are charged. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)