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

# API da Biblioteca de Anúncios da Meta

> Pesquise na Biblioteca de Anúncios da Meta por palavra-chave ou por anunciante e receba em JSON os anúncios veiculados no Facebook, Instagram, Messenger, WhatsApp e Threads, com texto, mídia, página de destino e plataformas.

Pesquise na Biblioteca de Anúncios da Meta em JSON pela API de tarefas assíncronas. Envie `taskType` `ADS` com `platform` `meta_ad_library` e uma palavra-chave em `query` ou o ID da página do Facebook de um anunciante em `pageId`. Uma busca custa **0.5 crédito a cada 30 anúncios** retornados. Para encontrar o ID da página de um anunciante pelo nome, envie `action` `advertisers`.

## Requisição

```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" } }'
```

Envie a tarefa e depois consulte `GET /v1/async/task/{id}` ou receba o webhook. Veja [Tarefas assíncronas](https://docs.querying.ai/pt/concepts/async-tasks.md). Uma busca de 30 anúncios costuma terminar em poucos segundos, e uma de 500 anúncios em cerca de um minuto.

## Parâmetros

* `action`: `search` (padrão), ou `advertisers`, que encontra anunciantes pelo nome.
* `query`: uma palavra-chave. Encontra as palavras do texto de um anúncio em qualquer ordem. Obrigatório sem `pageId`.
* `pageId`: o ID numérico da página do Facebook de um anunciante, como `266556540473351`. Lista os anúncios desse anunciante e, com `query`, busca entre eles.
* `country`: onde os anúncios foram veiculados, como código de país de duas letras, ou `ALL` para todos os países. Padrão `US`.
* `activeStatus`: `active` (padrão), `inactive` ou `all`.
* `limit`: de 1 a 500 anúncios. Padrão 30.
* `cursor`: o `nextCursor` de uma resposta anterior, para ler os anúncios seguintes.
* `searchType`: `keyword_unordered` (padrão) ou `keyword_exact_phrase`.
* `adType`: `all` (padrão), `political_and_issue_ads`, `housing_ads`, `employment_ads` ou `financial_products_and_services_ads`.
* `mediaType`: `all` (padrão), `image`, `meme`, `image_and_meme`, `video` ou `none`.
* `publisherPlatforms`: um ou mais de `facebook`, `instagram`, `audience_network`, `messenger`, `whatsapp` e `threads`, como array ou texto separado por vírgulas.
* `contentLanguages`: um ou mais códigos de idioma de duas letras.
* `startDate`, `endDate`: `YYYY-MM-DD`. Mantém os anúncios exibidos entre as duas datas.
* `sortBy`: `impressions_high_to_low` (padrão) ou `most_recent`. `impressions_low_to_high` exige `adType` `political_and_issue_ads`, os únicos anúncios que a biblioteca ordena assim.

Um valor que a biblioteca não consegue pesquisar é recusado com `400 VALIDATION_ERROR`, e `details` indica o campo.

## Ler mais anúncios

Uma resposta com mais anúncios a ler traz `nextCursor`. Envie-o como `cursor` com a mesma busca para receber os próximos anúncios, de novo até `limit`. As posições continuam da resposta anterior, e `nextCursor` é `null` quando a biblioteca não tem mais.

```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>" } }'
```

Um cursor só vale para a busca que o retornou: outro `query`, `pageId`, `country`, `activeStatus` ou filtro é recusado com `400 VALIDATION_ERROR`, enquanto `limit` pode mudar. O cursor cresce com os anúncios lidos antes dele, até cerca de 14 KB após mil anúncios; guarde-o como texto sem limite de tamanho. A biblioteca às vezes lista um anúncio duas vezes, então um anúncio pode voltar numa resposta seguinte; `libraryId` distingue as repetições.

## Encontrar um anunciante

`action` `advertisers` retorna as páginas do Facebook dos anunciantes cujo nome corresponde a `query`, como a busca da biblioteca as sugere. Envie o `pageId` escolhido para buscar os anúncios desse anunciante.

```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": []
}
```

Cada anunciante tem `position`, `pageId`, `name`, `category`, `likeCount`, `verified` (o selo azul da Meta), `country` (o país da página quando a Meta o informa, como a página britânica de uma marca global), `pageAlias`, `profileUrl`, `pictureUrl`, `instagramUsername`, `instagramFollowerCount`, `instagramVerified` e `libraryUrl`, que abre os anúncios dele na Biblioteca de Anúncios. `keywords` lista as buscas que a biblioteca sugere para o nome. A biblioteca busca o nome como a página o escreve: `Shokz` encontra as páginas da Shokz, e `샥즈` não encontra nenhuma. Um nome que nenhuma página usa termina com `advertisers` vazio. Uma busca de anunciantes aceita só `query` e `country`, e custa 0.5 crédito.

## Exemplo de resposta

```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"
        }
      ]
    }
  ]
}
```

## Campos do resultado

* A resposta repete `platform`, `action`, `country`, `query` ou `pageId`, `activeStatus` e os filtros recebidos.
* `totalCount` é a contagem de anúncios correspondentes da própria biblioteca, que a arredonda em buscas grandes. `returnedCount` conta os anúncios em `ads`, `hasMore` é `true` quando a biblioteca tem mais, que `nextCursor` lê, e `libraryUrl` abre a mesma busca na Biblioteca de Anúncios.
* Cada anúncio tem `position`, `libraryId`, `libraryUrl`, `isActive`, `startDate` e `endDate` (dias em UTC), `platforms`, `versions` (quantos anúncios usam este criativo e este texto), `format` (`IMAGE`, `VIDEO`, `CAROUSEL`, `DCO`, `DPA`, `MULTI_IMAGES` e outros), `body`, `title`, `caption`, `linkUrl`, `linkDescription`, `ctaText`, `ctaType` e `categories` (as categorias do anúncio segundo a biblioteca, como `POLITICAL` ou `EMPLOYMENT`).
* O anunciante é `pageId`, `pageName`, `pageProfileUrl`, `pageProfilePictureUrl`, `pageLikeCount` e `pageCategories`. Anúncios sobre temas sociais, eleições ou política acrescentam `byline`, quem pagou o anúncio, e `disclaimerLabel`, e uma parceria paga acrescenta a página do parceiro em `brandedContent`.
* A mídia é `images` (`url`, `resizedUrl`), `videos` (`hdUrl`, `sdUrl`, `previewImageUrl`) e `cards`, os cartões de um anúncio em carrossel ou de catálogo, cada um com `title`, `body`, `linkUrl`, `caption`, `linkDescription`, `ctaText`, `ctaType`, `imageUrl`, `resizedImageUrl` e `video`. Os outros textos, links, imagens e vídeos de um anúncio dinâmico ficam em `extraTexts`, `extraLinks`, `extraImages` e `extraVideos`.
* As URLs de mídia são links da CDN da Meta que expiram em poucos dias. Salve os arquivos de que precisar.
* Anúncios de catálogo (`DPA`, `DCO`) mantêm no texto os marcadores da biblioteca, como `{{product.name}}`.
* `spend`, `currency`, `impressions` e `reach` só aparecem onde a biblioteca os divulga: anúncios sobre temas sociais, eleições ou política, e anúncios exibidos na UE.
* Uma busca sem anúncios correspondentes termina com `ads` vazio e `totalCount` `0`.

## Preço

Uma busca reserva ao começar 0.5 crédito a cada 30 anúncios pedidos em `limit` e custa 0.5 crédito a cada 30 anúncios retornados, com mínimo de 0.5 crédito. A busca padrão de 30 anúncios custa 0.5 crédito, e uma busca com `limit` 500 reserva 8.5 créditos. Uma busca de anunciantes custa 0.5 crédito. Só as requisições concluídas são cobradas.

## Relacionado

* [Instagram](https://docs.querying.ai/pt/engines/instagram.md)
* [Threads](https://docs.querying.ai/pt/engines/threads.md)
* [Visão geral dos motores](https://docs.querying.ai/pt/engines/overview.md)
* [Créditos e limites](https://docs.querying.ai/pt/concepts/credits-and-limits.md)


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