> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Ad Library API

> Search the Meta Ad Library by keyword or advertiser and get the ads running on Facebook, Instagram, Messenger, WhatsApp and Threads as JSON, with their text, media, landing page and platforms.

Search the Meta Ad Library as JSON through the async task API. Send `taskType` `ADS` with `platform` `meta_ad_library`, and a keyword in `query` or an advertiser's Facebook page ID in `pageId`. A search costs **0.5 credits for every 30 ads** it returns. To find an advertiser's page ID by name, send `action` `advertisers`.

## Request

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "meta_ad_library", "pageId": "266556540473351", "country": "US" } }'
```

Submit the task, then poll `GET /v1/async/task/{id}` or receive its webhook. See [Async tasks](https://docs.querying.ai/concepts/async-tasks.md). A search of 30 ads usually completes in a few seconds, and a search of 500 ads in about a minute.

## Parameters

* `action`: `search` (default), or `advertisers`, which finds advertisers by name.
* `query`: A keyword. It matches the words in an ad's text in any order. Required unless `pageId` is set.
* `pageId`: An advertiser's numeric Facebook page ID, such as `266556540473351`. It lists that advertiser's ads, and with `query` it searches them.
* `country`: Where the ads ran, as a two-letter country code, or `ALL` for every country. Default `US`.
* `activeStatus`: `active` (default), `inactive` or `all`.
* `limit`: 1 to 500 ads. Default 30.
* `cursor`: The `nextCursor` of an earlier response, to read the ads after it.
* `searchType`: `keyword_unordered` (default) or `keyword_exact_phrase`.
* `adType`: `all` (default), `political_and_issue_ads`, `housing_ads`, `employment_ads` or `financial_products_and_services_ads`.
* `mediaType`: `all` (default), `image`, `meme`, `image_and_meme`, `video` or `none`.
* `publisherPlatforms`: One or more of `facebook`, `instagram`, `audience_network`, `messenger`, `whatsapp` and `threads`, as an array or comma-separated text.
* `contentLanguages`: One or more two-letter language codes.
* `startDate`, `endDate`: `YYYY-MM-DD`. Keeps the ads shown between the two days.
* `sortBy`: `impressions_high_to_low` (default) or `most_recent`. `impressions_low_to_high` needs `adType` `political_and_issue_ads`, the only ads the library sorts that way.

A value the library cannot search is rejected with `400 VALIDATION_ERROR`, and `details` names the field.

## Read more ads

A response with more ads to read carries `nextCursor`. Send it as `cursor` with the same search to receive the next ads, again up to `limit`. Positions continue from the last response, and `nextCursor` is `null` once the library has no more.

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "meta_ad_library", "pageId": "266556540473351", "country": "US", "limit": 500, "cursor": "<nextCursor>" } }'
```

A cursor works only with the search that returned it: a different `query`, `pageId`, `country`, `activeStatus` or filter is rejected with `400 VALIDATION_ERROR`, while `limit` can change. The cursor grows with the ads read before it, to about 14 KB after 1,000 ads, so store it as text without a length limit. The library sometimes lists an ad twice, so an ad can come again in a later response; `libraryId` tells the repeats apart.

## Find an advertiser

`action` `advertisers` returns the Facebook pages of the advertisers whose names match `query`, as the library's search box suggests them. Send the `pageId` you pick to search that advertiser's ads.

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "meta_ad_library", "action": "advertisers", "query": "soundcore", "country": "US" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "meta_ad_library",
  "action": "advertisers",
  "country": "US",
  "query": "soundcore",
  "returnedCount": 15,
  "advertisers": [
    {
      "position": 1,
      "pageId": "266556540473351",
      "name": "soundcore",
      "category": "Electronics",
      "likeCount": 147916,
      "verified": true,
      "country": null,
      "pageAlias": "soundcoreaudio",
      "profileUrl": "https://www.facebook.com/soundcoreaudio",
      "pictureUrl": "https://scontent-icn2-1.xx.fbcdn.net/v/t39.30808-1/793212698_1136613785698308_1883143393953135850_n.jpg",
      "instagramUsername": "soundcoreaudio",
      "instagramFollowerCount": 154040,
      "instagramVerified": true,
      "libraryUrl": "https://www.facebook.com/ads/library/?active_status=all&ad_type=all&country=US&is_targeted_country=false&media_type=all&search_type=page&view_all_page_id=266556540473351"
    }
  ],
  "keywords": []
}
```

Each advertiser has `position`, `pageId`, `name`, `category`, `likeCount`, `verified` (Meta's blue badge), `country` (the page's country where Meta names one, such as the UK page of a global brand), `pageAlias`, `profileUrl`, `pictureUrl`, `instagramUsername`, `instagramFollowerCount`, `instagramVerified` and `libraryUrl`, which opens the advertiser's ads in the Ad Library. `keywords` lists the searches the library suggests for the name. The library matches names as their pages spell them: `Shokz` finds the Shokz pages, and `샥즈` finds none. A name no page carries completes with an empty `advertisers`. An advertiser search takes only `query` and `country`, and costs 0.5 credits.

## Response example

```json theme={"theme":"css-variables"}
{
  "platform": "meta_ad_library",
  "action": "search",
  "country": "US",
  "pageId": "266556540473351",
  "activeStatus": "active",
  "totalCount": 849,
  "returnedCount": 30,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiMnhZaDJ3VVhxdGNKRXBaOSIsImMiOiJBUUhUaWVMOXYweDloLXhIYzdQV1BYSGxNcE9rcUthVVMxNnUydTNxYWpJN2FBd2lOYW8tQ0lNWm16bDE4endJcFBWViIsInMiOjAsInAiOjMwfQ",
  "libraryUrl": "https://www.facebook.com/ads/library/?active_status=active&ad_type=all&country=US&media_type=all&search_type=page&view_all_page_id=266556540473351",
  "ads": [
    {
      "position": 1,
      "libraryId": "2033461067351971",
      "libraryUrl": "https://www.facebook.com/ads/library/?id=2033461067351971",
      "pageId": "266556540473351",
      "pageName": "soundcore",
      "pageProfileUrl": "https://www.facebook.com/soundcoreaudio/",
      "pageLikeCount": 147918,
      "pageCategories": ["Electronics"],
      "isActive": true,
      "startDate": "2026-11-14",
      "endDate": "2026-11-19",
      "platforms": ["FACEBOOK", "INSTAGRAM"],
      "versions": 5,
      "format": "DCO",
      "body": "🎧Anker soundcore AeroClip 2 — the world's clearest open-ear clip-on earbuds. Now $143.99 + free earrings.",
      "title": "AeroClip 2 Open-Ear",
      "caption": "soundcore.com",
      "linkUrl": "https://www.soundcore.com/aeroclip-2-best-clear-calls-clip-on-open-earbuds-boa",
      "linkDescription": "Four colors, match.",
      "ctaText": "Shop now",
      "ctaType": "SHOP_NOW",
      "images": [],
      "videos": [],
      "cards": [
        {
          "title": "Made to Match",
          "body": "🍎Four finishes made to match. AeroClip 2, the first open-ear clip-on with Apple MFi certification.",
          "linkUrl": "https://www.soundcore.com/aeroclip-2-best-clear-calls-clip-on-open-earbuds-boa",
          "linkDescription": "Four colors, match.",
          "ctaText": "Shop Now",
          "ctaType": "SHOP_NOW",
          "imageUrl": "https://scontent-dfw6-2.xx.fbcdn.net/v/t39.35426-6/897874467_980515998005271_8997541605873239828_n.jpg"
        }
      ]
    }
  ]
}
```

## Result fields

* The response echoes `platform`, `action`, `country`, `query` or `pageId`, `activeStatus` and the filters it was given.
* `totalCount` is the library's own count of the matching ads, which the library rounds for large searches. `returnedCount` counts the ads in `ads`, `hasMore` is `true` when the library has more, which `nextCursor` reads, and `libraryUrl` opens the same search in the Ad Library.
* Each ad has `position`, `libraryId`, `libraryUrl`, `isActive`, `startDate` and `endDate` (days in UTC), `platforms`, `versions` (how many ads use this creative and text), `format` (`IMAGE`, `VIDEO`, `CAROUSEL`, `DCO`, `DPA`, `MULTI_IMAGES` and others), `body`, `title`, `caption`, `linkUrl`, `linkDescription`, `ctaText`, `ctaType` and `categories` (the library's categories of the ad, such as `POLITICAL` or `EMPLOYMENT`).
* The advertiser is `pageId`, `pageName`, `pageProfileUrl`, `pageProfilePictureUrl`, `pageLikeCount` and `pageCategories`. Ads about social issues, elections or politics add `byline`, who paid for the ad, and `disclaimerLabel`, and a paid partnership adds the partner's page in `brandedContent`.
* Media is `images` (`url`, `resizedUrl`), `videos` (`hdUrl`, `sdUrl`, `previewImageUrl`) and `cards`, the cards of a carousel or catalog ad, each with its own `title`, `body`, `linkUrl`, `caption`, `linkDescription`, `ctaText`, `ctaType`, `imageUrl`, `resizedImageUrl` and `video`. A dynamic ad's other texts, links, images and videos are in `extraTexts`, `extraLinks`, `extraImages` and `extraVideos`.
* Media URLs are Meta CDN links that expire after a few days. Save the files you need.
* Catalog ads (`DPA`, `DCO`) keep the library's placeholders, such as `{{product.name}}`, in their text.
* `spend`, `currency`, `impressions` and `reach` appear only where the library discloses them: ads about social issues, elections or politics, and ads shown in the EU.
* A search with no matching ads completes with an empty `ads` and `totalCount` `0`.

## Price

A search holds 0.5 credits for every 30 ads its `limit` asks for, and is charged 0.5 credits for every 30 ads it returns, at least 0.5 credits. The default search of 30 ads costs 0.5 credits, and a search with `limit` 500 holds 8.5 credits. An advertiser search costs 0.5 credits. Only completed requests are charged.

## Related

* [Instagram](https://docs.querying.ai/engines/instagram.md)
* [Threads](https://docs.querying.ai/engines/threads.md)
* [Engine overview](https://docs.querying.ai/engines/overview.md)
* [Credits and limits](https://docs.querying.ai/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.