Documentos
Ctrl+K Buscar Alt+[Alt+] Guías
Obtener clave API

API · Biblioteca de anuncios

Biblioteca de anuncios de Meta

GET /api/v1/adlibrary searches Meta (Facebook / Instagram) ads with your API key. /api/adlibrary is a supported alias. Auth and metering match the Referencia de la API. MCP equivalent: buscar_anuncios_en_Facebook (and encontrar_productos_ganadores, paquete_de_inspiración_creativa) — see MCP · Referencia de herramientas.

OBTENER /api/v1/adlibrary

curl -sS -G -H "X-API-Key: $WH_API_KEY" "{origin}/api/v1/adlibrary" \
  --data-urlencode "keyword=skincare" \
  --data-urlencode "searchkeyword=adtext" \
  --data-urlencode "countries=US" \
  --data-urlencode "sorting=reach" \
  --data-urlencode "page=0" \
  --data-urlencode "min=" --data-urlencode "max=" \
  --data-urlencode "from=" --data-urlencode "to=" \
  --data-urlencode "mediafilter=" --data-urlencode "scroll=" \
  --data-urlencode "scaling=" --data-urlencode "niches=" \
  --data-urlencode "fromlastseen=" --data-urlencode "tolastseen=" \
  --data-urlencode "activestatus="

{
  "data": [
    {
      "id": "1284756102394857",
      "page_name": "Glow Beauty Co.",
      "ad_creative_body": "This serum changed my skin in 14 days…",
      "ad_snapshot_url": "https://www.facebook.com/ads/library/?id=1284756102394857",
      "media_type": "video",
      "started": "2024-05-12",
      "reach": 184000,
      "ad_rank": 3
    }
  ],
  "total": 240,
  "scroll": "eyJwYWdlIjoxfQ=="
}

La llamada de visualizaciones de anuncios de Meta dentro de la aplicación /api/fb-ads with the same query shape — copy a working request from your browser's network tab and swap the path to /api/v1/adlibrary.

Protección de entradas (claves de consulta obligatorias)

El punto final solo devuelve su carga útil JSON principal cuando todas las claves siguientes están presentes en la cadena de consulta (se permite una cadena vacía):

palabra clave de búsqueda, palabra clave, min, países, de, a, clasificación, filtro de medios, página, máximo, desplazarse, escalado, nichos, desde la última vez que se le vio, tolastseen, estado activo

Si falta alguno, la respuesta no es la carga útil habitual de la lista (evítalo en los clientes).

Además, la puerta interior requiere juicio establecido en la consulta o a ha iniciado sesión / clave API resuelta sesión. Con una Clave X-API, cumples automáticamente con los requisitos de la sesión. De lo contrario, la respuesta es:

{"error":"logged_out"}

Todos de consulta

Todo lo que aparece a continuación se lee desde el cadena de consulta (de la misma forma que /api/fb-ads (en la aplicación).

isset puerta (debe estar presente; se admite una cadena vacía)

La misma lista que Defensa exterior arriba:
palabra clave de búsqueda, palabra clave, min, máximo, países, de, a, clasificación, filtro de medios, página, desplazarse, escalado, nichos, desde la última vez que se le vio, tolastseen, estado activo.

Muy recomendable en todos

El controlador lee sitio web, idiomas, filtro de tipo de página, dirección de ordenación, aplicaciones, y temas sin pasar por eso isset lista. Duplica el panel de control y envía al menos sitio web=Todos, idiomas=Todos, pagetypefilter= (vacío = todos los tipos de página), orden=descendente, apps=Todas, temas=Todos para que el comportamiento se ajuste a la interfaz de usuario y las claves opcionales estén siempre definidas.

Snake_case aliases (MCP-parity names)

/api/v1/adlibrary (and the /api/adlibrary alias) also accepts the same snake_case argument names as the MCP buscar_anuncios_en_Facebook tool, normalized server-side to the internal keys below (FacebookAdsFilterSpec::publicQueryAliases()). When both names are sent, the internal name wins. Highlights:

Alias Internal key
país / países, exclude_countries países, excluir países
niche / nichos nichos
technology / technologies sitio web
language / idiomas, exclude_languages idiomas, excluir idiomas
theme / temas, aplicaciones, exclude_apps temas, aplicaciones, excluir aplicaciones
media_type, page_type, ad_score, low_impressions, rank_growth_filter filtro de medios, filtro de tipo de página, filtro de puntuación publicitaria, pocas impresiones, rankgrowthfilter
ad_created_from / ad_created_to de / a
last_seen_from / last_seen_to desde la última vez que se le vio / tolastseen
product_created_from / product_created_to producto_de / producto_a
page_created_from / page_created_to página de / página
min_duplicates / max_duplicates min / máximo
gasto_mínimo_en_publicidad / gasto_máximo_en_publicidad, ad_spend_timeframe gasto en defensa / gasto máximo en publicidad, periodo de inversión publicitaria
min_reach / max_reach, reach_timeframe minreach / maxreach, intervalo de tiempo
min_monthly_visits / max_monthly_visits mintraffic / maxtraffic
min_days_running / max_days_running mindays / días máximos
min_active_ads / max_active_ads minactiveads / maxactiveads
min_active_ads_growth / max_active_ads_growth, active_ads_growth_period minactiveadsgrowth / maxactiveadsgrowth, activeadsgrowthperiod
min_reach_growth / max_reach_growth, reach_growth_period minreachgrowth / maxreachgrowth, reachgrowthperiod
min_ad_rank / max_ad_rank minadrank / maxadrank
min_page_likes / max_page_likes, precio_mínimo / precio_máximo, min_copy_length / max_copy_length, min_video_length / max_video_length, min_products_on_store / max_products_on_store minpagelikes / maxpagelikes, precio mínimo / precio máximo, longitud del mincópilo / longitud máxima de copia, duración mínima del vídeo / longitud máxima del vídeo, minproductsonstore / maxproductsonstore
ordenar por / orden de clasificación clasificación / dirección de ordenación
active_status estado activo

On the API route the entry-guard keys are defaulted server-side (Dashboard::fbAdsPublicBaseQuery()), so a request like ?keyword=skincare&last_seen_from=2026-01-01&last_seen_to=2026-02-01 is valid without sending every isset-gate key. When palabra clave is set and palabra clave de búsqueda is empty, searchkeyword=All is applied automatically.

Autenticación / sesión /

Parámetro Función
(ninguno) Con Clave X-API, la solicitud se ejecuta con tu cuenta (es como si hubieras iniciado sesión).
juicio Si se establece (p. ej., trial=true), se aplican las reglas de búsqueda de soluciones ganadoras anónimas; si se combinan con filtros en la página ≠ 0, pueden devolver {"message":"need_account"}.

Paginación, cursor, eliminación de

Parámetro Notas
página Índice de páginas que empieza por 0.
desplazarse Cursor de paginación profunda desde la búsqueda; vacío en la primera solicitud, luego se copia el desplazarse valor de la respuesta JSON anterior.
La próxima vez que haya rebajas Unix segundos; se utiliza cuando ordenar=fecha_de_encuentro (La primera página suele utilizar una marca de tiempo de referencia de la interfaz de usuario).
token_de_búsqueda Opcional [a-zA-Z0-9_-]+; corbatas anuncios por marca limitar a una pestaña o búsqueda en la sesión.

por palabra clave

Parámetro Valores permitidos / típicos
palabra clave Texto libre; codificado como URL; convertido a minúsculas en el servidor.
palabra clave de búsqueda '', Todo, URL de destino, nombre de la página, texto del anuncio, nombre del producto (debe estar en este conjunto cuando palabra clave (no está vacía).

Anuncios activos, escalado, medios, tipo de página, AdScore,

Parámetro Valores (que coincidan con los filtros de Meta Ads de la aplicación)
estado activo Cadena verdad o falso (solo activos frente a incluir los inactivos).
escalado '' (ninguno), sin reducción de escala, extrapolación, reducción de escala.
filtro de medios '' / efecto de omisión = todos los formatos; en caso contrario vídeos, imágenes, carrusel, dco (corresponde a formato de visualización (en ES).
filtro de tipo de página '' = todos; productos, colecciones, embudos, nofunnels.
filtro de puntuación publicitaria '' = ninguno; ganador (Fundada), escalado (Tiene potencial), pruebas (Sin determinar). Requiere el nivel correspondiente dentro de la aplicación.
pocas impresiones '' = mostrar todo; ocultar = excluir las filas con un número muy bajo de impresiones (mismo comportamiento que el filtro del panel de control).
rankgrowthfilter '' = none; comma-separated subset of rising, stable, declining (rank momentum vs historic rank_history; same semantics as the dashboard Crecimiento en el ranking filter).
minadrank, maxadrank Positive integers — within-brand ad rank (lower = stronger for that brand; #3 / N in the UI). Empty = no bound. Matches the dashboard Posición en el ranking de anuncios filter.

Parámetro Valores
dirección de ordenación asc o desc (si está vacío, se establece por defecto en desc).
clasificación '' (Ninguno → orden aleatorio cuando no se baraja), trending, cantidad del conjunto de anuncios, última conexión, fecha de hallazgo, mostrecent (ad start date / comenzó), adspend, el más longevo, alcanzar, visitas mensuales, anuncios activos en la página, días corriendo, toprank (when enabled for your deployment). días corriendo puede que no aplique una rama de ordenación específica (se comporta como None a menos que cambie el producto).

Presupuesto, alcance (con ventana emergente), tráfico, días de publicación, precio, texto publicitario, duración del vídeo, anuncios activos en

Parámetro Notas
gasto en defensa, gasto máximo en publicidad Números enteros / cadenas numéricas. maxadspend=999999 se considera que «no hay límite máximo» a efectos de la comprobación adspend. Para aplicar adspend significativo adspend , puede ser necesario un nivel superior dentro de la aplicación.
periodo de inversión publicitaria todos, 7, 30, 90 — Ventana para adspend (valores no válidos → todos).
minreach, maxreach Números enteros. Puede requerir un nivel superior dentro de la aplicación.
intervalo de tiempo El mismo conjunto permitido que periodo de inversión publicitaria.
mintraffic, maxtraffic Store monthly-visits range (absolute). May require a higher in-app tier.
minstorerevenue, maxstorerevenue Est. monthly store revenue range in USD (overlaps store_traffic.monthly_revenue_{min,max} on wlads). Same tier gate as traffic filters.
storebasedin Comma-separated ISO2 shop origin countries → store_traffic.shop_origin_country on wlads (same values as Explore Shops Con sede en / stores metadata.country).
storevisitorcountrymain Comma-separated ISO2 — country tied for top visitor share (store_traffic.visitor_country_main).
storevisitorcountryamong Comma-separated ISO2 — country appears in traffic mix (store_traffic.top_countries).
storevisitorcountryexclude Comma-separated ISO2 — exclude ads whose store has traffic from that country.
trustpilotrating Trustpilot stars dash range on store_traffic.trustpilot.ratings (p. ej., 4-5, 2.5-3.5). Same tier gate as traffic filters.
trustpilotreviews Trustpilot review-count dash range on store_traffic.trustpilot.total_reviews (p. ej., 1000-10000, 100000-100000000).
storecreated_from, storecreated_to Store creation window (A-M-D) on store_traffic.first_product_created_at. Same tier gate as traffic filters. UI chip param: datestorecreated (Lightpick display range).
mingrowth, maxgrowth, growthperiod Monthly visit growth range, as a signed % change in store traffic (UI values: 25 = 25%). growthperiod selects the window: 1 (default) or 3 months → ranges on store_traffic.monthly_visits_growth_{1,3}m (indexed at 1/100 of the UI %, e.g. 1695 → 16.95). Empty min/max = no bound; negatives select declining stores. Same in-app tier gate as mintraffic.
minactiveadsgrowth, maxactiveadsgrowth, activeadsgrowthperiod Page active ads % growth (panel de control Active ads growth, Page tab). UI min/max are human percent (p. ej., 25 = 25%; negatives allowed). activeadsgrowthperiod tokens: 1w, 14d, 1m, 3m (por defecto 1m; legacy 7d→1w, 2m→14d, 30d→1m, 90d→3m). Server maps tokens to indexed baselines total_active_ads_on_page_growth_{1w,14d,1m,3m} and filters on ((\texttt{total_active_ads_on_page} - \texttt{baseline}) / \texttt{baseline} \times 100) (baseline is the prior-period active-ad count, not a precomputed pct field). Dashboard labels: 1 week→1w (7d), 2 weeks→14d (14d), 1 month→1m (30d).
minreachgrowth, maxreachgrowth, reachgrowthperiod Ad cumulative EU reach % growth (panel de control Ad EU Reach Growth, EU/UK tab). Same UI % and period semantics as ads growth. Ranges total_eu_views_growth_pct_{period} only (not reach_growth_pct_*, which is page-level reach). Same in-app tier gate as minreach / maxreach.
mindays, días máximos Filtro de rango de días consecutivos; puede requerir un nivel superior dentro de la aplicación.
precio mínimo, precio máximo
longitud del mincópilo, longitud máxima de copia
duración mínima del vídeo, longitud máxima del vídeo
minactiveads, maxactiveads Límite del estilo «Anuncios activos en la página» (el flujo de prueba puede insertar minactiveads (del lado del servidor).
minpagelikes, maxpagelikes Facebook page likes range on indexed page_like_count (ads without the field are excluded when a min is set).
minigfollowers, maxigfollowers Instagram followers range on wlads tracking.igfollowers (denormalized at ingest; no pages-index join). Currently disabled in app (Ads::WLADS_IG_FOLLOWERS_FILTER_ENABLED); enable after field backfill + dashboard UI.

Data dependency — monthly visit growth. mingrowth/maxgrowth range on store_traffic.monthly_visits_growth_{1,3}m on the wlads index. The 1-month field is widely populated; 3-month may return no matches until the indexer backfills that scalar.

Data dependency — wlads % growth filters. minactiveadsgrowth requires total_active_ads_on_page plus total_active_ads_on_page_growth_{1w,14d,1m,3m} en wlads (baselines must be prior counts, not deltas). minreachgrowth uses total_eu_views_growth_pct_{period} when backfilled. Sparse baselines reduce match counts; use broader ranges when testing.

Fechas (cadenas de caracteres, normalmente A-M-D)

Parámetro Significado
de, a Anuncio creación (comenzó).
desde la última vez que se le vio, tolastseen Última vez que se le vio (actualizado el).
producto_de, producto_a Ventana de creación de productos.
página de, página Ventana de creación de páginas.

Los intervalos de fechas abiertos se normalizan en el servidor (por ejemplo, solo de establecer → a se puede configurar para que coincida de).

Catálogo: países, tiendas, nichos, idiomas, aplicaciones, temas,

Parámetro Formato
países Todo o separados por comas ISO 3166-1 alfa-2 códigos (p. ej., EE. UU., Reino Unido).
sitio web Todo o códigos de tienda separados por comas (p. ej., SH = Shopify — (consulte el filtro de sitios web del panel de control).
nichos Todo o segmentos separados por comas (códigos predefinidos, /Ruta/... rutas del catálogo de nichos o identificadores numéricos (normalizados en el servidor). Si la lista contiene compras, el servidor añade producto.
idiomas Todo o códigos de idioma separados por comas (como en el panel de control #idioma).
aplicaciones Todo o separados por comas numérico ID de aplicaciones (los mismos valores que el filtro de aplicaciones integradas).
temas Todo o cadenas de temas separadas por comas (descubrir a través de GET /api/themes).
excluir países, excluir sitios web, excluir idiomas, excluir nichos, excluir aplicaciones Los mismos patrones separados por comas que en el lado de inclusión; nichos normalizados como nichos.

Enlaces directos, reproducción aleatoria,

Parámetro Notas
identificador de página a partir de la URL Facebook page_id: limita los anuncios a una sola página.
id_del_producto ID de producto de Shopify.
barajar Cualquier valor no vacío que se considere verdadero → modo aleatorio (ordenación aleatoria; ventana predeterminada opcional de «último visto»).
anuncios por marca 1, 2, 3, 5, 10 solo: número máximo de anuncios por marca cuando se aplica la lógica de aleatorización o de límite por marca.

Validación /

No válido min o máximo (fuera del intervalo 0…90000000) puede dar como resultado {"error":"value_not_in_range_1"} o _2, o un formato que no sea JSON falso el cuerpo en casos extremos.

Descubrir lo válido nichos y temas (estas rutas no requieren clave API)

Las integraciones deben obtener los valores permitidos del archivo JSON de descubrimiento, no a base de conjeturas:

Punto final Objetivo
GET /api/niche-counts Devoluciones { "niches": [ { "code": "…", "count": N }, … ], "total_with_niche": … } creado a partir del mismo índice de anuncios de Meta que utiliza el producto. Utiliza el código cadenas (separadas por comas en nichos / excluir nichos) como el conjunto de referencia que aparece realmente en los datos publicitarios. Opcional: refresh=1 omite la caché del disco para una solicitud.
GET /api/themes Devuelve un objeto JSON con un temas lista (valores máximos + recuentos, almacenada en caché durante aproximadamente 1 hora). Consulta opcional: q — si la longitud es ≥ 2, búsqueda de subcadenas para autocompletado. Opcional: límite (por defecto 200, máximo 500). Utilizar el tema devuelto nombres/claves exactamente igual que temas= valores separados por comas en /api/adlibrary.

Atajos predefinidos para nichos («chips» de la interfaz de usuario): La aplicación también ofrece funciones orientadas al usuario códigos de dos letras (p. ej., CG, POR, SP) en el filtro de nicho. Esos son segmentos válidos en nichos= del mismo modo que los envía el navegador.

Segmentos de nicho numéricos: Los valores se resuelven utilizando el catálogo de nichos del servidor (rutas como /Ropa/... y numéricos ids (asignación a nombres canónicos en la búsqueda). Si un segmento es desconocido, se puede dejar tal cual — se prefiere /api/recuentos-de-nichos en lugar de inventar excusas.

Nota: /api/recuentos-de-nichos y /api/temas son descubrimiento ayudantes y no consumen créditos de la API de Meta Ad Library de la misma manera /api/adlibrary Es posible que tu implementación siga requiriendo un inicio de sesión u otra política antes de estas rutas.

Funciones (actualización de JSON)

En las cuentas que no cuentan con el nivel de producto requerido, algunos filtros o modos de ordenación devuelven 200 con un cuerpo JSON breve (el mensaje de actualización es dentro de la banda(no siempre un error HTTP 403):

Respuesta Condición (simplificada)
{"upgrade":"standard_adspend"} Se ha aplicado el filtro de gasto publicitario, o adspend
{"upgrade":"standard_reach"} Filtro de alcance o clasificación=alcance
{"upgrade":"standard_traffic"} Filtro de tráfico
{"upgrade":"standard_daysrunning"} Filtro de días consecutivos o ordenar=días consecutivos
{"upgrade":"standard_adscore"} filtro de puntuación publicitaria conjunto

Otras destacadas#

  • {"message":"need_account"} — Anónimo juicio solicitudes que superan el límite de uso permitido (restricciones del flujo de la versión de prueba).
  • Carga útil de éxito: objeto JSON que incluye datos (anuncios), opcional mensaje (sugerencias de filtrado comprensibles para los usuarios), total + total_relation (computed on every page for API-key / MCP requests; the dashboard UI fetches totals separately via count_only=1), desplazarse (deep-pagination cursor), and free-tier credit fields when applicable. total can still be null for query shapes that post-filter in PHP (e.g. rankgrowthfilter). Each ad may include ad_rank (integer position within its brand/page) and rank_history (time series used for momentum / Rank growth filtering in the dashboard). Programmatic and MCP payloads include these fields when present in search results.