# Facebook Ad Library Filters

Get the filter context available for ad searches: suggested advertiser pages with their ad counts, and the content languages the library can be searched in. The library also defines facet lists for countries, cities, targeted regions, reached regions and disclaimers, but those are empty in the public library itself; they are returned as empty lists rather than omitted, and an empty list is the correct response rather than a failed lookup. A single request covers one upstream lookup and costs one credit.

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

## 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 | Optional keyword to tailor the suggested advertiser pages. |
| `country` | string | No | Two-letter ISO country code. |
| `ad_type` | string | No | Ad category: ALL, POLITICAL_AND_ISSUE_ADS, CREDIT_ADS, FINANCIAL_PRODUCTS_AND_SERVICES_ADS, EMPLOYMENT_ADS, HOUSING_ADS or UNCATEGORIZED_ADS. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/facebook-ad-library/filters?country=DE"
```

## Example response

```json
{
    "filters": {
        "pages": [
            {
                "page_id": "15087023444",
                "page_name": "Nike",
                "ad_count": 512
            }
        ],
        "content_languages": [
            "de",
            "en"
        ],
        "countries": [],
        "cities": [],
        "targeted_regions": [],
        "reached_regions": [],
        "disclaimers": []
    },
    "populated_facet_lists": [
        "pages",
        "content_languages"
    ],
    "empty_facet_lists": [
        "countries",
        "cities",
        "targeted_regions",
        "reached_regions",
        "disclaimers"
    ],
    "empty_facet_lists_note": "The public Ad Library returns several of these facet lists empty. An empty list is the correct response, not a failed lookup; each list above is derived from what this response actually carried.",
    "response_time_ms": 380
}
```

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