> ## 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 de la Biblioteca de anuncios de Meta

> Busca en la Biblioteca de anuncios de Meta por palabra clave o por anunciante y recibe como JSON los anuncios que circulan en Facebook, Instagram, Messenger, WhatsApp y Threads, con su texto, contenido multimedia, página de destino y plataformas.

Busca en la Biblioteca de anuncios de Meta y recibe JSON mediante la API de tareas asíncronas. Envía `taskType` `ADS` con `platform` `meta_ad_library` y una palabra clave en `query` o el ID de la página de Facebook de un anunciante en `pageId`. Una búsqueda cuesta **0.5 créditos por cada 30 anuncios** que devuelve. Para encontrar el ID de página de un anunciante por su nombre, envía `action` `advertisers`.

## Solicitud

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

Envía la tarea y luego consulta `GET /v1/async/task/{id}` o recibe su webhook. Consulta [Tareas asíncronas](https://docs.querying.ai/es/concepts/async-tasks.md). Una búsqueda de 30 anuncios suele completarse en unos segundos, y una de 500 anuncios en alrededor de un minuto.

## Parámetros

* `action`: `search` (por defecto), o `advertisers`, que busca anunciantes por su nombre.
* `query`: una palabra clave. Busca las palabras del texto de un anuncio en cualquier orden. Obligatorio si no hay `pageId`.
* `pageId`: el ID numérico de la página de Facebook de un anunciante, como `266556540473351`. Reúne los anuncios de ese anunciante y, con `query`, busca entre ellos.
* `country`: dónde circularon los anuncios, como código de país de dos letras, o `ALL` para todos los países. Por defecto, `US`.
* `activeStatus`: `active` (por defecto), `inactive` o `all`.
* `limit`: de 1 a 500 anuncios. Por defecto, 30.
* `cursor`: el `nextCursor` de una respuesta anterior, para leer los anuncios que siguen.
* `searchType`: `keyword_unordered` (por defecto) o `keyword_exact_phrase`.
* `adType`: `all` (por defecto), `political_and_issue_ads`, `housing_ads`, `employment_ads` o `financial_products_and_services_ads`.
* `mediaType`: `all` (por defecto), `image`, `meme`, `image_and_meme`, `video` o `none`.
* `publisherPlatforms`: uno o más de `facebook`, `instagram`, `audience_network`, `messenger`, `whatsapp` y `threads`, como array o como texto separado por comas.
* `contentLanguages`: uno o más códigos de idioma de dos letras.
* `startDate`, `endDate`: `YYYY-MM-DD`. Conserva los anuncios mostrados entre las dos fechas.
* `sortBy`: `impressions_high_to_low` (por defecto) o `most_recent`. `impressions_low_to_high` requiere `adType` `political_and_issue_ads`, los únicos anuncios que la biblioteca ordena así.

Un valor que la biblioteca no puede buscar se rechaza con `400 VALIDATION_ERROR`, y `details` indica el campo.

## Leer más anuncios

Una respuesta con más anuncios por leer trae `nextCursor`. Envíalo como `cursor` con la misma búsqueda para recibir los anuncios siguientes, de nuevo hasta `limit`. Las posiciones siguen desde la respuesta anterior, y `nextCursor` es `null` cuando la biblioteca no tiene más.

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

Un cursor solo sirve para la búsqueda que lo devolvió: si cambian `query`, `pageId`, `country`, `activeStatus` o un filtro, se rechaza con `400 VALIDATION_ERROR`, mientras que `limit` puede cambiar. El cursor crece con los anuncios leídos antes, hasta unos 14 KB tras mil anuncios, así que guárdalo como texto sin límite de longitud. La biblioteca a veces lista un anuncio dos veces, por lo que un anuncio puede volver en una respuesta posterior; `libraryId` distingue las repeticiones.

## Encontrar un anunciante

`action` `advertisers` devuelve las páginas de Facebook de los anunciantes cuyo nombre coincide con `query`, como las sugiere el buscador de la biblioteca. Envía el `pageId` que elijas para buscar los anuncios de ese 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 tiene `position`, `pageId`, `name`, `category`, `likeCount`, `verified` (la insignia azul de Meta), `country` (el país de la página cuando Meta lo indica, como la página británica de una marca global), `pageAlias`, `profileUrl`, `pictureUrl`, `instagramUsername`, `instagramFollowerCount`, `instagramVerified` y `libraryUrl`, que abre sus anuncios en la Biblioteca de anuncios. `keywords` enumera las búsquedas que la biblioteca sugiere para el nombre. La biblioteca busca el nombre tal como lo escribe la página: `Shokz` encuentra las páginas de Shokz y `샥즈` no encuentra ninguna. Un nombre que ninguna página lleva termina con `advertisers` vacío. Una búsqueda de anunciantes solo admite `query` y `country`, y cuesta 0.5 créditos.

## Ejemplo de respuesta

```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 del resultado

* La respuesta repite `platform`, `action`, `country`, `query` o `pageId`, `activeStatus` y los filtros recibidos.
* `totalCount` es el recuento de anuncios coincidentes de la propia biblioteca, que lo redondea en las búsquedas grandes. `returnedCount` cuenta los anuncios de `ads`, `hasMore` es `true` cuando la biblioteca tiene más, que `nextCursor` permite leer, y `libraryUrl` abre la misma búsqueda en la Biblioteca de anuncios.
* Cada anuncio tiene `position`, `libraryId`, `libraryUrl`, `isActive`, `startDate` y `endDate` (días en UTC), `platforms`, `versions` (cuántos anuncios usan este contenido y este texto), `format` (`IMAGE`, `VIDEO`, `CAROUSEL`, `DCO`, `DPA`, `MULTI_IMAGES` y otros), `body`, `title`, `caption`, `linkUrl`, `linkDescription`, `ctaText`, `ctaType` y `categories` (las categorías del anuncio según la biblioteca, como `POLITICAL` o `EMPLOYMENT`).
* El anunciante es `pageId`, `pageName`, `pageProfileUrl`, `pageProfilePictureUrl`, `pageLikeCount` y `pageCategories`. Los anuncios sobre temas sociales, elecciones o política añaden `byline`, quién pagó el anuncio, y `disclaimerLabel`, y una colaboración pagada añade la página del socio en `brandedContent`.
* El contenido multimedia es `images` (`url`, `resizedUrl`), `videos` (`hdUrl`, `sdUrl`, `previewImageUrl`) y `cards`, las tarjetas de un anuncio por secuencia o de catálogo, cada una con su `title`, `body`, `linkUrl`, `caption`, `linkDescription`, `ctaText`, `ctaType`, `imageUrl`, `resizedImageUrl` y `video`. Los demás textos, enlaces, imágenes y vídeos de un anuncio dinámico están en `extraTexts`, `extraLinks`, `extraImages` y `extraVideos`.
* Las URL del contenido multimedia son enlaces de la CDN de Meta que caducan a los pocos días. Guarda los archivos que necesites.
* Los anuncios de catálogo (`DPA`, `DCO`) conservan en su texto los marcadores de la biblioteca, como `{{product.name}}`.
* `spend`, `currency`, `impressions` y `reach` solo aparecen donde la biblioteca los publica: anuncios sobre temas sociales, elecciones o política, y anuncios mostrados en la UE.
* Una búsqueda sin anuncios coincidentes se completa con `ads` vacío y `totalCount` `0`.

## Precio

Una búsqueda retiene al empezar 0.5 créditos por cada 30 anuncios que pide `limit`, y cuesta 0.5 créditos por cada 30 anuncios que devuelve, con un mínimo de 0.5 créditos. La búsqueda predeterminada de 30 anuncios cuesta 0.5 créditos, y una búsqueda con `limit` 500 retiene 8.5 créditos. Una búsqueda de anunciantes cuesta 0.5 créditos. Solo se cobran las solicitudes completadas.

## Relacionado

* [Instagram](https://docs.querying.ai/es/engines/instagram.md)
* [Threads](https://docs.querying.ai/es/engines/threads.md)
* [Resumen de motores](https://docs.querying.ai/es/engines/overview.md)
* [Créditos y límites](https://docs.querying.ai/es/concepts/credits-and-limits.md)


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