Facebook Ad Library API: la guía del desarrollador para ads_archive

La Facebook Ad Library API es el endpoint oficial de la Graph API de Meta, ads_archive, para buscar en el archivo público de anuncios de forma programática. Te autenticas con un token de acceso de usuario, pasas el parámetro obligatorio ad_reached_countries, y filtras por palabras clave, Page IDs, tipo de anuncio, fechas y plataformas para recibir resultados en JSON. La cobertura es limitada: anuncios políticos y de temas sociales en todo el mundo durante siete años, más todos los anuncios entregados en la UE o el Reino Unido durante un año. El gasto y las impresiones se devuelven como rangos, lo que la convierte en datos de investigación competitiva gratuitos pero acotados.

Has buscado en la ad library desde un navegador, encontraste lo que necesitabas, y ahora quieres los mismos datos en JSON: extracciones programadas, un dashboard de competidores, un dataset de investigación. Para eso exactamente sirve la Ad Library API (oficialmente la Meta Ad Library API desde el rebranding), y es genuinamente gratuita. También es la API más malentendida en la superficie de desarrolladores de Meta, porque la mayoría de los desarrolladores llegan esperando acceso programático a todo lo que pueden ver en el sitio web, y descubren que el archivo tiene sus propias reglas.

Si todavía no has trabajado con la herramienta subyacente, empieza con nuestra guía completa de la Meta Ads Library, porque la API hereda cada propiedad de la versión web y luego la acota aún más. Esta guía cubre la parte que importa a los desarrolladores: qué devuelve realmente la API, la configuración de acceso, el endpoint ads_archive con ejemplos funcionales de curl y Python, límites de tasa y códigos de error, y la lista honesta de las cosas que nunca te dará, junto con qué usar en su lugar.

Qué cubre realmente la Facebook Ad Library API

Antes de escribir una sola línea de código, interioriza el alcance, porque explica casi todas las respuestas vacías que vas a obtener. El archivo detrás de la API contiene exactamente dos categorías de anuncios:

Todo lo demás simplemente no existe para la API. Un anuncio comercial que solo se emitió en Estados Unidos no está archivado, no es buscable y no es recuperable. Esa pregunta de Stack Overflow de 2019 sobre por qué las búsquedas por palabra clave solo devuelven anuncios políticos todavía posiciona hoy porque la confusión nunca desapareció. La búsqueda por palabra clave en anuncios comerciales solo funciona donde esos anuncios se entregaron a usuarios de la UE o el Reino Unido, ya que esos son los únicos anuncios comerciales en el archivo.

Dos cambios recientes endurecieron esto aún más. La cobertura del Reino Unido se aplica a anuncios que se emitieron después del 1 de julio de 2025, así que el archivo del Reino Unido todavía se está construyendo hacia un año completo continuo. Y a principios de octubre de 2025, Meta dejó de aceptar por completo anuncios políticos, electorales y de temas sociales en la UE, en respuesta al reglamento de la UE sobre Transparencia y Segmentación de la Publicidad Política. El archivo histórico político de la UE sigue siendo consultable, pero ahora está congelado: las consultas de anuncios políticos de la UE posteriores a esa fecha no devuelven nada porque ninguno sigue activo.

Para un desarrollador, la prueba práctica es simple. Si tu caso de uso es investigación de anuncios políticos en cualquier lugar, o investigación de cualquier anuncio en mercados de la UE y el Reino Unido, la API oficial funciona. Si necesitas anuncios comerciales de EE. UU. por palabra clave, no puede ayudarte, y deberías saltar directamente a la sección de alternativas.

Ad Library API frente a Marketing API

Estas dos se confunden constantemente, y no comparten nada más que un nombre de dominio. La Marketing API gestiona publicidad que te pertenece: crea campañas, sube creatives y lee el rendimiento de cuentas publicitarias sobre las que tienes permisos. La Ad Library API es acceso de solo lectura al archivo público de transparencia de los anuncios de todos los demás.

Las diferencias atraviesan cada capa. La Marketing API necesita permisos ads_read o ads_management y a menudo App Review; la Ad Library API no necesita ninguno de los dos. La Marketing API devuelve el gasto y los resultados exactos de tus anuncios; la Ad Library API devuelve rangos por bandas para los anuncios políticos y de UE/Reino Unido de otras personas. Si quieres tus propios datos de campaña de forma programática, quieres la Marketing API. Esta guía trata de la otra.

Cómo obtener acceso a la Ad Library API

El acceso requiere tres pasos únicos. Ninguno es difícil, pero el primero implica un período de espera, así que empiézalo antes de necesitar los datos.

Paso 1: confirma tu identidad

Debido a que el archivo incluye datos de anuncios políticos, Meta exige que cada usuario de la API confirme su identidad y ubicación, el mismo proceso que completan los anunciantes para publicar anuncios políticos. Ve a facebook.com/ID con la sesión iniciada y sigue las indicaciones. Espera tener que subir un documento de identidad oficial y confirmar tu ubicación de residencia. La aprobación normalmente tarda unos días. Esto es por cuenta y única vez, pero saltárselo es el fallo de configuración más común: tu token será válido y tus consultas seguirán siendo rechazadas.

Paso 2: crea una app en Meta for Developers

Regístrate en Meta for Developers si aún no lo has hecho, y luego crea una nueva app desde My Apps. El tipo de app más simple funciona; la app es solo un contenedor que te permite generar tokens. No necesitas añadirle productos, y la Ad Library API no requiere App Review, porque solo estás leyendo datos públicos del archivo.

Paso 3: genera un access token

Abre el Graph API Explorer desde el menú de herramientas de desarrollador, selecciona tu app y genera un token de acceso de usuario. No se necesitan permisos especiales más allá de los predeterminados; lo que importa es que el usuario detrás del token haya completado el paso 1.

Los tokens del Explorer son de corta duración, expiran en una hora o dos. Para cualquier cosa más allá de una prueba rápida, cámbialo por un long-lived token, que dura unos 60 días, usando las herramientas de tokens en el panel de desarrollador. Los pipelines programados necesitan una rutina de renovación, porque cuando el token caduca tus solicitudes empiezan a fallar con el error 190 hasta que pones uno nuevo.

Para verificar que todo funciona, ejecuta una consulta de prueba en el Explorer:

ads_archive? ad_reached_countries=['US']&ad_type=POLITICAL_AND_ISSUE_ADS&search_terms='election'

Si vuelve JSON, ya estás dentro.

Consultar el endpoint ads_archive

Cada solicitud es un HTTP GET contra una URL:

https://graph.facebook.com/v25.0/ads_archive

El segmento de versión sigue los lanzamientos trimestrales de la Graph API de Meta (v25.0 a mediados de 2026). Dos cosas son obligatorias en cada llamada: tu access_token y ad_reached_countries, un array de códigos de país ISO (o ALL) que define dónde se entregaron los anuncios que quieres. Cada consulta también necesita search_terms o search_page_ids; si omites ambos, la API rechaza la llamada con un error de parámetro en lugar de devolverlo todo. Recuerda la regla de alcance: ad_reached_countries=['US'] solo puede sacar a la luz anuncios políticos y de temas sociales, mientras que ['GB'] o cualquier código de la UE también saca a la luz anuncios comerciales.

Los parámetros que importan

La lista completa de parámetros está en la referencia de ads_archive de Meta, pero estos son con los que se construyen las consultas reales:

Un puñado de otros (delivery_by_region, estimated_audience_size_min y max) son filtros exclusivos de anuncios políticos; en otro caso la API los ignora o da error.

Elegir tus campos

Por defecto obtienes un registro mínimo: id, ad_snapshot_url, horas de inicio y fin de entrega, y page_id. Todo lo demás debe solicitarse explícitamente a través del parámetro fields. Los que vale la pena conocer:

• Todos los anuncios: page_name, ad_creative_bodies, ad_creative_link_titles, ad_creative_link_captions, ad_creative_link_descriptions, publisher_platforms, languages, ad_creation_time
• Solo anuncios políticos y de temas sociales: spend y impressions (rangos por bandas, desde menos de 100 hasta más de 1 millón), currency, demographic_distribution, delivery_by_region, estimated_audience_size, bylines
• Anuncios entregados en la UE y el Reino Unido: eu_total_reach, total_reach_by_location, age_country_gender_reach_breakdown, target_ages, target_gender, target_locations, y beneficiary_payers (solo UE)

Los campos que no aplican a un anuncio dado simplemente están ausentes de su objeto JSON, así que escribe tu código de parsing de forma defensiva.

Ejemplo: curl

El ejemplo canónico de la propia documentación de Meta, ampliado con fields:

curl -G \
 -d "search_terms='california'" \
 -d "ad_type=POLITICAL_AND_ISSUE_ADS" \
 -d "ad_reached_countries=['US']" \
 -d "ad_active_status=ALL" \
 -d "fields=id, page_name, ad_creative_bodies, ad_delivery_start_time, spend, impressions" \
 -d "access_token=<ACCESS_TOKEN>" \
 "https://graph.facebook.com/v25.0/ads_archive"

Ejemplo: Python con paginación

Los resultados llegan en páginas, y el trabajo real está en recorrerlas en bucle. Este script extrae cada anuncio archivado de la página de un competidor tal como se entregó en el Reino Unido:

import requests

TOKEN = "YOUR_LONG_LIVED_TOKEN"
url = "https://graph.facebook.com/v25.0/ads_archive"
params = {
 "access_token": TOKEN,
 "ad_reached_countries": '["GB"]',
 "search_page_ids": '["123456789"]',
 "ad_active_status": "ALL",
 "fields": "id, page_name, ad_creative_bodies,"
 "ad_delivery_start_time, ad_delivery_stop_time,"
 "publisher_platforms, ad_snapshot_url, eu_total_reach",
 "limit": 250,
}

ads = []
while url:
 resp = requests. get(url, params=params, timeout=60)
 payload = resp. json()
 if "error" in payload:
 raise RuntimeError(payload["error"]["message"])
 ads. extend(payload. get("data", []))
 url = payload. get("paging", {}). get("next")
 params = {} # the next URL already carries every parameter

print(f"Collected {len(ads)} ads")

Cambia el page ID, el país y los fields según tu caso de uso. Como código de referencia, el propio Ad Library API Script Repository de Meta en GitHub incluye una interfaz de línea de comandos simple y ejemplos en Python, aunque apunta a versiones más antiguas de la Graph API y ya no se actualiza activamente.

Límites de tasa, paginación y errores comunes

La paginación se basa en cursores. Cada respuesta contiene un array data y un objeto paging con cursores y una URL next; has llegado al final cuando data vuelve vacío. El tamaño de página predeterminado es de 25 anuncios, y el parámetro limit lo aumenta. Si lo llevas demasiado alto, cambias problemas de límite de tasa por problemas de timeout en consultas pesadas, por eso la mayoría de los scripts de producción se asientan alrededor de unos pocos cientos de anuncios por página.

Los límites de tasa en ads_archive son dinámicos y no se publican. Escalan por app y por token, y el uso intensivo se limita mediante throttling en lugar de medirse con precisión. Tres hábitos te mantienen bajo el techo: solicita solo los campos que necesitas, acota las consultas con códigos de país y search_page_ids en lugar de palabras clave amplias, y añade backoff exponencial cada vez que veas el error 613. Para trabajos recurrentes, agrupar hasta 10 page IDs por llamada es la ganancia de eficiencia más barata disponible.

Los errores con los que realmente te vas a encontrar:

Una peculiaridad estructural atrapa a todo el mundo tarde o temprano: no existe un endpoint para obtener un solo anuncio por su Library ID. Si tienes un ID del sitio web, consulta la página del anunciante con search_page_ids y filtra los resultados del lado del cliente para el id que coincida.

Lo que la API no te va a dar

La Ad Library API es una herramienta de transparencia, y Meta trazó sus límites deliberadamente. Conocerlos de antemano te ahorra diseñar funciones que los datos no pueden soportar.

• Sin métricas de rendimiento. Sin clics, CTR, conversiones o conteos de engagement, para ningún anuncio, nunca. El gasto y las impresiones solo existen para anuncios políticos y de UE/Reino Unido, y solo como rangos.
• Sin archivos de creative. Las respuestas incluyen un ad_snapshot_url que renderiza el anuncio en un navegador, pero nunca archivos de imagen o video. Descargar medios masivamente desde las páginas de snapshot no está soportado y choca con los términos de servicio de Meta.
• Sin detalle real de segmentación. No puedes ver intereses, públicos personalizados ni lookalikes. Los anuncios de la UE y el Reino Unido solo exponen las selecciones amplias de edad, género y ubicación.
• Una memoria comercial corta. Los anuncios no políticos caen del archivo un año después de su última impresión. Los anuncios políticos persisten durante siete. Si necesitas un historial más largo, tienes que recopilar de forma continua y construir tu propio archivo.

Ninguno de estos es un bug, y ninguna consulta por ingeniosa que sea los evita. Cuando la brecha importa, cambias de herramienta.

Alternativas cuando la API es demasiado limitada

Ajusta la herramienta a la brecha en lugar de pelear contra la API oficial.

Necesitas anuncios comerciales fuera de la UE y el Reino Unido. Este es el grande, y la respuesta es hacer scraping del sitio web de Ad Library, que muestra anuncios comerciales activos en todos los países aunque la API no los sirva. Scrapers construidos a propósito y APIs wrapper (Apify actors desde alrededor de 0,75 $ por 1.000 anuncios, más servicios como SearchApi y ScrapeCreators que venden los mismos datos como JSON limpio) se encargan de la automatización del navegador por ti. Los trade-offs son reales: estás fuera de los términos de la API oficial, los esquemas se rompen cuando Meta actualiza el sitio, y tomar esa ruta es una decisión de riesgo deliberada que asume el comprador, no algo que recomendemos.

No eres desarrollador, o tu equipo no lo es. La mayoría de las tareas de investigación competitiva que parecen proyectos de API en realidad son problemas de exportación: alguien quiere los anuncios de la competencia o los datos de su propia cuenta en una hoja de cálculo. Las herramientas de exportación masiva sin código cubren eso sin tokens ni scripts, y nuestra guía para exportar datos de anuncios de Facebook repasa las opciones de principio a fin.

Estás haciendo investigación formal. Académicos e investigadores que califiquen pueden solicitar la Meta Content Library y su API, la sucesora de CrowdTangle, que cubre publicaciones públicas y contenido más allá de los anuncios con una verificación más estricta y garantías más fuertes. Para estudiar el alcance orgánico y la actividad coordinada junto con los anuncios, es el instrumento más completo.

Solo necesitas un puñado de anunciantes, ocasionalmente. Sáltate la ingeniería. El sitio web más sus filtros nativos, revisados semanalmente, le gana a mantener un pipeline de renovación de tokens para datos que podrías leer en diez minutos.

Preguntas frecuentes

¿Es gratuita la Facebook Ad Library API? Sí, completamente. Sin niveles de uso, sin créditos. Los costes son indirectos: tiempo de verificación de identidad, ingeniería de límites de tasa, y las restricciones de alcance que pueden empujarte hacia alternativas de pago.

¿Puedo ver todos los anuncios de la competencia en cualquier país? No. Los anuncios políticos y de temas sociales en todo el mundo, más los anuncios entregados en la UE o el Reino Unido, son todo el archivo. Los anuncios comerciales exclusivos de EE. UU. simplemente están ausentes.

¿Puedo descargar imágenes y videos de anuncios a través de la API? No. Obtienes un ad_snapshot_url para ver cada anuncio en un navegador. Los archivos de medios nunca aparecen en las respuestas, y recolectarlos masivamente desde las páginas de snapshot incumple los términos de Meta.

¿Puedo buscar un solo anuncio por su Library ID? No. No existe un endpoint por ID. Consulta la página del anunciante con search_page_ids y filtra del lado del cliente por el id que quieras.

¿Cuántos resultados puede devolver una consulta? 25 por página por defecto, ampliable mediante el parámetro limit, con paginación por cursor a través de paging.next hasta que data vuelve vacío. Unos pocos cientos por página es el techo fiable antes de que los timeouts se vuelvan comunes.

¿Qué significa el error 613? Superaste el límite de tasa. Los límites son dinámicos y no se publican, así que incorpora backoff exponencial, solicita menos campos, y agrupa page IDs para mantenerte bajo el umbral.

¿Necesito App Review para usar la Ad Library API? No. Necesitas confirmación de identidad en facebook.com/ID, una app de desarrollador y un token de acceso de usuario. App Review solo aplica a datos privados de usuarios y permisos de cuenta publicitaria.

¿Cuál es el límite de tasa de la Ad Library API? Meta no publica ninguno. El throttling es dinámico por app y por token. Trata los errores 613 como la señal, reduce la frecuencia cuando aparezcan, y espacia las extracciones programadas en lugar de lanzarlas todas de golpe.

Construye teniendo en cuenta el alcance

La Facebook Ad Library API es excelente en exactamente aquello para lo que fue creada: acceso gratuito, oficial y programático a la transparencia de anuncios políticos en todo el mundo y a todo anuncio que toca a usuarios de la UE y el Reino Unido. Dentro de ese alcance es la elección correcta todas las veces, y la configuración (confirmación de identidad, una app de desarrollador, un long-lived token) toma una tarde más unos días de espera de verificación.

El modo de fallo es construir contra el archivo que imaginaste en lugar del archivo que realmente existe. Así que decide de antemano: la investigación política o de UE/Reino Unido pasa por ads_archive; la inteligencia comercial de todos los países significa scrapers o APIs de datos de terceros; los problemas con forma de hoja de cálculo merecen herramientas de exportación sin código en lugar de un proyecto de ingeniería. Sea cual sea el camino que encaje, el lado de los datos de la investigación competitiva ahora es la mitad fácil. La mitad difícil es lo que siempre ha sido: convertir lo que aprendes de los anuncios de otras personas en tus propios tests creativos, a un volumen que realmente te enseñe algo.