API de la Biblioteca de anuncios de Meta: acceso y ejemplos

La API de la Biblioteca de anuncios de Meta (en inglés, Meta Ad Library API) es el endpoint ads_archive de la Graph API: devuelve en JSON los mismos anuncios que ves en la web de la Biblioteca, con sus fechas de entrega, texto, plataformas y, para los anuncios mostrados en la UE, alcance y segmentación. Para usarla tienes que confirmar tu identidad, crear una aplicación en Meta for Developers y enviar un token de acceso en cada petición. No da el gasto ni las ventas de los anuncios comerciales; sí da desde cuándo está activo cada uno.

Esta guía es la versión técnica de la guía de la Biblioteca de anuncios de Meta: requisitos, parámetros, qué campos llegan según el tipo de anuncio, un ejemplo en curl y en Python, los límites y cómo sacar de ahí los días activos de cada anuncio.

Qué devuelve la API de la Biblioteca de anuncios

Según la página oficial de la API, cubre dos conjuntos de anuncios:

• Los anuncios sobre temas sociales, elecciones o política entregados en cualquier país durante los últimos siete años.
• Los anuncios de cualquier tipo entregados en la UE (y el Reino Unido) durante el último año. Esto es lo que permite consultar anuncios comerciales de marcas españolas, y existe por el artículo 39 del Reglamento de Servicios Digitales.

La referencia de ads_archive lo deja claro en el parámetro de países: los anuncios que no llegaron a ningún lugar de la UE solo se devuelven si tratan de temas sociales, elecciones o política. Por eso no puedes sacar los anuncios comerciales que una marca lanza solo en Estados Unidos o México.

Es una API de solo lectura: el endpoint admite lecturas y nada más. No sirve para gestionar tus campañas; para eso está la Marketing API, que es otra cosa.

Acceso: requisitos para usar la API

Meta pide tres pasos en la página de la API:

1. Confirmar tu identidad y tu ubicación con el mismo proceso que se exige para publicar anuncios sobre temas sociales, elecciones o política. Se hace desde facebook.com/ID.
2. Crear una cuenta de Meta for Developers y aceptar su política de la plataforma.
3. Crear una aplicación desde «Mis apps». Es la que identifica tus peticiones.

Access token: el «api key» de la Biblioteca

La API no usa una clave fija. Cada petición lleva un access_token de usuario, generado con tu aplicación; lo más rápido para probar es el explorador de la Graph API. Según la documentación de tokens de Meta, el token por defecto caduca en horas y uno de larga duración dura en general unos 60 días. Se obtiene canjeando el corto desde tu servidor:

curl -G "https://graph.facebook.com/v26.0/oauth/access_token" \
  -d "grant_type=fb_exchange_token" \
  -d "client_id={app-id}" \
  -d "client_secret={app-secret}" \
  -d "fb_exchange_token={token-corto}"

Un token caducado no se puede canjear: hay que volver a iniciar sesión. Si automatizas consultas, apunta la fecha de caducidad; el error 190 («token de acceso no válido») es la señal de que toca renovarlo. Y no publiques el token ni el secreto de la app en el código.

Documentación: parámetros de ads_archive

La versión actual de la Graph API es la v26.0, publicada el 29 de julio de 2026 según el registro de cambios de Meta. Estos son los parámetros que más se usan, de la referencia oficial:

Parámetro	Qué hace
ad_reached_countries	Países donde se entregó el anuncio, en código ISO (["ES"]) o ALL
ad_type	ALL por defecto; también POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS y FINANCIAL_PRODUCTS_AND_SERVICES_ADS
ad_active_status	ACTIVE por defecto, INACTIVE o ALL
search_terms	Palabras del anuncio, hasta 100 caracteres; un espacio funciona como «y»
search_type	KEYWORD_UNORDERED por defecto o KEYWORD_EXACT_PHRASE para la frase exacta
search_page_ids	Hasta diez ids de página de Facebook
ad_delivery_date_min / _max	Rango de fechas de entrega, AAAA-MM-DD, ambos incluidos
publisher_platforms	FACEBOOK, INSTAGRAM, MESSENGER, AUDIENCE_NETWORK, THREADS, entre otras
media_type	IMAGE, VIDEO, MEME, NONE o ALL
languages	Idiomas del anuncio en ISO 639-1

Dos detalles que ahorran tiempo. Meta avisa de que los términos de búsqueda no se traducen: busca en el idioma de los anuncios. Y la API no busca páginas por nombre; para seguir a una marca necesitas su id de página.

Campos: anuncios comerciales de la UE frente a políticos

Lo que devuelve cada anuncio se pide con fields, y la referencia del anuncio archivado indica qué campo existe para qué anuncios:

Disponibles para todos los anuncios	Solo anuncios entregados en la UE (o UE y Reino Unido)	Solo anuncios políticos o sociales
id, page_id, page_name	eu_total_reach (alcance estimado en la UE)	spend (gasto, en intervalos)
ad_creation_time	beneficiary_payers (beneficiario y pagador)	impressions (en intervalos)
ad_delivery_start_time, ad_delivery_stop_time	target_ages, target_gender, target_locations	currency
ad_creative_bodies, ad_creative_link_titles, ad_creative_link_descriptions, ad_creative_link_captions	age_country_gender_reach_breakdown (alcance por país, edad y sexo)	bylines (quién lo financia)
ad_snapshot_url, languages, publisher_platforms	total_reach_by_location (alcance por ubicación: solo UE, Reino Unido y Brasil)	demographic_distribution, delivery_by_region, estimated_audience_size

La consecuencia práctica: de un anuncio comercial de tu competencia en España sabes cuándo empezó y paró, qué decía, dónde salió, a cuántas cuentas de la UE llegó y a quién apuntaba. No sabes cuánto gastó. La imagen o el vídeo no vienen en el JSON: ad_snapshot_url es un enlace para ver el anuncio archivado, y Meta recuerda que el material descargado solo puede usarse para análisis y conforme a sus condiciones.

Tutorial: una petición con curl y con Python

Todos los anuncios entregados en España de una página, activos y parados, con los campos que sirven para medir duración y variantes:

curl -G "https://graph.facebook.com/v26.0/ads_archive" \
  --data-urlencode 'ad_reached_countries=["ES"]' \
  --data-urlencode 'search_page_ids=["ID_DE_LA_PAGINA"]' \
  -d "ad_type=ALL" \
  -d "ad_active_status=ALL" \
  -d "fields=id,page_name,ad_delivery_start_time,ad_delivery_stop_time,ad_creative_bodies,publisher_platforms,eu_total_reach" \
  -d "limit=100" \
  -d "access_token=$META_TOKEN"

La respuesta trae una lista data y un bloque paging. Para recorrer todos los resultados, sigue paging.next hasta que no exista o data venga vacía. En Python, con requests:

import json, os, requests

url = "https://graph.facebook.com/v26.0/ads_archive"
params = {
    "ad_reached_countries": json.dumps(["ES"]),
    "search_terms": "envío gratis",
    "search_type": "KEYWORD_EXACT_PHRASE",
    "ad_type": "ALL",
    "ad_active_status": "ACTIVE",
    "fields": "id,page_id,page_name,ad_delivery_start_time,ad_creative_bodies",
    "limit": 100,
    "access_token": os.environ["META_TOKEN"],
}

ads = []
while url:
    res = requests.get(url, params=params, timeout=30).json()
    if "error" in res:
        raise RuntimeError(res["error"])
    ads.extend(res.get("data", []))
    url = res.get("paging", {}).get("next")
    params = None  # la URL de "next" ya lleva todos los parámetros

print(len(ads), "anuncios")

Meta publicó un repositorio de scripts en Python para tirar de la API desde la línea de comandos. No se actualiza desde febrero de 2025, así que úsalo como referencia, no como cliente listo.

Límites de uso

Meta no publica una cifra concreta de peticiones para ads_archive. Se aplican los límites de la Graph API, que dependen de la aplicación y del usuario del token, y la referencia del endpoint lista el error 613 como límite superado. Los códigos que verás:

• 4: la aplicación ha llegado a su límite.
• 17: el usuario del token ha llegado al suyo.
• 613: límite propio del endpoint.

Las respuestas pueden traer la cabecera X-App-Usage, con el porcentaje consumido de llamadas, tiempo y CPU en la ventana de una hora; cuando el tiempo o la CPU llegan a 100, las llamadas pueden empezar a limitarse. En la práctica: pide solo los campos que uses, filtra por fechas con ad_delivery_date_min, consulta las páginas de una en una y espera antes de reintentar.

Cómo calcular los días activos de un anuncio

Meta no publica gasto ni ventas de los anuncios comerciales, así que la mejor señal pública de que un anuncio funciona es cuánto tiempo lo mantiene encendido su anunciante: pocos anunciantes pagan semanas por un anuncio que pierde dinero. Con la API se calcula con dos campos:

• ad_delivery_start_time: cuándo el anunciante quiso que empezara la entrega (UTC).
• ad_delivery_stop_time: cuándo quiso que parara. Meta indica que en blanco significa que sigue hasta que se detenga o se acabe el presupuesto.

La fórmula: días activos = (fecha de fin o hoy) − fecha de inicio. Si ad_delivery_stop_time está vacío o es una fecha futura (una parada programada), el anuncio sigue en marcha y cuentas hasta hoy. Ojo con ad_creation_time: es cuando se creó, no cuando empezó a mostrarse.

La segunda señal es el texto repetido. Cuando un mensaje funciona, el anunciante lo duplica con otras imágenes o vídeos. Normaliza ad_creative_bodies (minúsculas, sin emojis ni signos) y agrupa por ese texto: un mismo mensaje con varias versiones lanzadas en fechas distintas es uno que ha pasado el filtro.

Así trabaja Lanzads: cada semana lee esta API para los anunciantes que sigue, calcula los días activos de cada anuncio y agrupa las variantes por texto. Qué cuenta como «mucho tiempo» y cuándo se agota un anuncio lo explicamos en cuánto tiempo debe estar activo un anuncio de Facebook; y si solo quieres comprobar uno a mano, en cómo saber si un anuncio de Facebook está activo.

Alternativas a la API: scrapers y sus riesgos

Si no quieres pasar por la confirmación de identidad, en marketplaces como Apify hay scrapers de la Biblioteca hechos por terceros que cobran por uso. Tienen tres problemas:

1. Las condiciones de Meta. Sus condiciones de uso prohíben acceder a datos de sus productos o recogerlos con medios automatizados sin su permiso previo. La API es el permiso.
2. Fragilidad. Leen la web, no un contrato de datos: cuando Meta cambia la página o bloquea la IP, dejan de funcionar.
3. Datos sin garantía. Los mantienen terceros, no Meta, y sus campos no tienen por qué coincidir con los de la API.

Si no programas, las herramientas para espiar anuncios son otra vía. Y si prefieres que te llegue hecho: cada lunes, los anuncios de tu competencia y de tu sector en España que llevan semanas activos, lo que han lanzado y apagado y qué te toca probar, sacado de esta misma API. Cuéntanos qué vendes y a quién quieres vigilar.