Advertisement Search

Advertisement Search devuelve anuncios individuales que Pubrio ha capturado, una fila por anuncio. Cada fila incluye la creatividad (titular, imagen o video, página de destino), dónde se mostró, cuándo se ejecutó y el rango de impresiones que reporta la fuente.

curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["stripe.com"],
    "source_types": ["linkedin", "facebook"],
    "active_dates": ["2026-08-01", "2026-08-31"],
    "per_page": 25
  }'

Cuándo usarlo

Investigación creativa de la competencia — qué está diciendo un competidor, en qué países, en qué formato.
Intención — una empresa que acaba de empezar a anunciarse en un nuevo mercado se está expandiendo hacia él. Combínalo con target_locations.
Proxies de inversión — reach_tiers y los filtros de métrica advertisement_* clasifican empresas por volumen publicitario sin una cifra de gasto.

Para totales y tendencias usa Advertisement Insights. Para encontrar empresas por su actividad publicitaria en lugar de los anuncios en sí, usa los filtros advertisement_* en Company Search.

Fuentes

`source_type`	Notas
`linkedin`	Etiquetas de formato detalladas (`Single Image Ad`, `Document Ad`, …)
`facebook`	Abarca Facebook, Instagram, Messenger, Threads y Audience Network; acótalo con `publisher_platforms`. `meta` se acepta como alias.
`google`	Mayormente `text`
`tiktok`
`apple`

total_impressions es null en los anuncios cuya fuente no publica una estimación, y esos anuncios nunca coinciden con reach_tiers.

Acotar a una empresa

Clave	Valor
`domains`	`["stripe.com"]`
`linkedin_urls`	`["https://www.linkedin.com/company/stripe"]`
`companies`	`["5378845d-…"]` — valores de `domain_search_id`

Se permite una búsqueda sin empresa, por ejemplo {"target_locations": ["SG"], "source_types": ["linkedin"]}. Solo se devuelven los anuncios ya vinculados a una empresa de Pubrio, a menos que configures is_include_unlinked_companies: true.

Filtros

Fuente y formato

Clave	Tipo	Coincide con
`source_types`	`string[]`	`linkedin`, `facebook`, `google`, `tiktok`, `apple`. Cualquiera de los listados. Los valores desconocidos no coinciden con nada y se reflejan en `metadata.unsupported_source_types`.
`exclude_source_types`	`string[]`	Mismo vocabulario, excluido.
`advertisement_formats`	`string[]`	Formatos canónicos: `image`, `video`, `text`, `carousel`, `dynamic_product`, `document`, `message`, `event`, `article`, `spotlight`, `follow`, `job`, `engagement`. Consulta Formatos.
`publisher_platforms` / `exclude_publisher_platforms`	`string[]`	`facebook`, `instagram`, `messenger`, `threads`, `audience_network`. Solo anuncios de Meta.

Texto

Clave	Tipo	Coincide con
`headlines`	`string[]`	Texto del titular, cualquiera de los listados.
`search_term` / `search_terms`	`string` / `string[]`	Titular y descripción.

Fechas

Clave	Tipo	Coincide con
`active_dates`	`[from, to]`	Anuncios en ejecución en algún momento dentro de la ventana, incluidos los que comenzaron antes y siguen activos. Esta es la ventana que usa Advertisement Insights. Los anuncios sin `started_at` se cuentan desde `created_at`. Ambas fechas son obligatorias; límites de día en UTC.
`start_dates`	`[from, to]`	`started_at` dentro de la ventana — anuncios que se lanzaron entonces. Límites de día según la zona horaria del workspace.
`end_dates`	`[from, to]`	`ended_at` dentro de la ventana. Límites de día según la zona horaria del workspace.
`created_at`	fecha o timestamp ISO	Capturado por Pubrio en o después de este instante (UTC), para sincronización incremental.

start_dates oculta la mayoría de las campañas activas de una empresa, porque una campaña lanzada en marzo puede seguir ejecutándose en agosto. Recurre a active_dates a menos que quieras específicamente los lanzamientos.

Dónde se mostró

Clave	Tipo	Coincide con
`target_locations`	`string[]`	Países donde se entregó el anuncio. OR por defecto; agrega `{"key": "target_locations", "operator": "and"}` a `filter_conditions` para exigir todos los países.
`exclude_target_locations`	`string[]`	Países a excluir.
`company_locations`	`string[]`	País de la sede del anunciante.

Alcance y volumen

Clave	Tipo	Coincide con
`reach_tiers`	`string[]`	Banda de impresiones del anuncio: `lt_1k`, `1k_10k`, `10k_50k`, `50k_100k`, `100k_500k`, `500k_1m`, `1m_plus`. Los anuncios sin valor de `total_impressions` nunca coinciden.
`advertisement_active_ads`, `advertisement_running_ads`, `advertisement_total_ads`, `advertisement_platform_count`, `advertisement_format_count`, `advertisement_impressions_estimate`	`[min, max]`	Filtra anuncios por los totales del anunciante, p. ej. `advertisement_active_ads: [10, null]` devuelve anuncios de empresas con al menos diez anuncios activos.
`advertisement_country_activity`	objeto	`{ "country": "US", "rank": [null, 100] }` — anuncios de los 100 principales anunciantes en ese país.

Enriquecimiento

Clave	Tipo	Notas
`is_realtime_enrichment`	`boolean`	Si la búsqueda no devuelve nada, rastrea las fuentes ahora y vuelve a buscar. Solo búsquedas acotadas a una empresa.
`enrichment_mode`	`default` / `latest`	`latest` vuelve a rastrear en cada llamada sin importar la caché.
`is_include_unlinked_companies`	`boolean`	También devuelve anuncios que Pubrio no pudo vincular a un registro de empresa (`is_company_matched: false`).

Paginación y orden

per_page, page e is_ascending_order se comportan como en cualquier búsqueda. Las filas se ordenan por created_at (momento de captura), las más recientes primero.

Cómo se ve una fila

{
  "advertisement_id": "58fa840e-08aa-4ac8-a204-8b185fd62f8e",
  "advertisement_search_id": "58fa840e-08aa-4ac8-a204-8b185fd62f8e",
  "created_at": "2026-09-01T02:00:07.068Z",
  "last_modified": "2026-09-01T02:00:07.068Z",
  "started_at": "2026-08-24T00:00:00.000Z",
  "ended_at": "2026-08-31T00:00:00.000Z",
  "title": "Your 2026 peak season prep checklist is here",
  "source_type": "linkedin",
  "advertisement_format": "Single Image Ad",
  "advertisement_format_normalized": "image",
  "is_company_matched": true,
  "advertiser": "Stripe",
  "advertiser_url": "https://www.linkedin.com/company/2135371",
  "advertisement_url": "https://www.linkedin.com/ad-library/detail/1518455034",
  "total_impressions": "< 1k",
  "total_impressions_lower": null,
  "total_impressions_upper": 1000,
  "image_url": "https://buckets.pubrio.com/images/public/….jpg",
  "video_url": null,
  "carousel_images": null,
  "destination_url": "https://stripe.com/industries/retail?trk=…",
  "raw_link_url": null,
  "target_country_codes": ["US"],
  "publisher_platforms": null,
  "companies": {
    "domain_search_id": "5378845d-7726-4817-aba9-ced8c5f41dee",
    "company_name": "Stripe",
    "domain": "stripe.com",
    "country_code": "US",
    "…": "…"
  }
}

ended_at es null mientras el anuncio sigue en ejecución.
advertisement_format es la etiqueta propia de la fuente; advertisement_format_normalized es el slug por el que puedes filtrar.
destination_url es la página de destino sin envolver; raw_link_url conserva el rastreador de clics exactamente como se capturó.
total_impressions es el texto de la fuente; el par _lower / _upper es el rango interpretado.

`metadata` en este endpoint

"metadata": {
  "profile": null,
  "filters": { "domains": ["stripe.com"], "source_types": ["tiktok", "bogus"], "per_page": 25, "language": "en" },
  "ignored_fields": [],
  "applied_source_types": ["tiktok"],
  "unsupported_source_types": ["bogus"],
  "coverage_notes": [{ "source_type": "tiktok", "scope": "eea_uk_ch" }]
}

Clave	Cuándo aparece	Significado
`ignored_fields`	Siempre	Claves del cuerpo que el endpoint descartó
`applied_source_types`	Se envió `source_types`	Valores que se reconocieron
`unsupported_source_types`	Se envió un valor desconocido	Esos valores no coincidieron con nada
`coverage_notes`	Cuando aplica	Notas de cobertura para las fuentes solicitadas
`skipped_source_types`	Cuando aplica	`[{ "source_type", "reason" }]` — fuentes no aplicadas para los `target_locations` solicitados

Recetas

Creatividades de la competencia en un mercado
Anuncios de LinkedIn de alto alcance
Anuncios de Meta solo en Instagram

cURL

curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["adyen.com", "checkout.com"],
    "target_locations": ["SG", "AU"],
    "advertisement_formats": ["video", "carousel"],
    "active_dates": ["2026-08-01", "2026-09-04"],
    "per_page": 25
  }'

cURL

curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_locations": ["US"],
    "source_types": ["linkedin"],
    "reach_tiers": ["100k_500k", "500k_1m", "1m_plus"],
    "active_dates": ["2026-08-01", "2026-09-04"],
    "per_page": 25
  }'

El companies.domain_search_id de cada fila es una empresa que está invirtiendo fuertemente en LinkedIn en EE. UU. este mes.

cURL

curl -X POST https://api.pubrio.com/companies/advertisements/search \
  -H "pubrio-api-key: $PUBRIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": ["nike.com"],
    "source_types": ["facebook"],
    "publisher_platforms": ["instagram"],
    "exclude_publisher_platforms": ["facebook"],
    "per_page": 25
  }'

Relacionado

Referencia de Advertisement Search

Todos los parámetros y campos de respuesta.

Advertisement Insights

Totales, niveles de alcance y creatividades de una empresa en una ventana de tiempo.

Filtros de actividad publicitaria

Encuentra empresas por su actividad publicitaria en Company Search.

Enumeraciones y constantes

Fuentes, formatos, plataformas y niveles de alcance.

Monitor

Búsqueda

Filtros

Personas

Expansión

Cuándo usarlo

Fuentes

Acotar a una empresa

Filtros

Fuente y formato

Texto

Fechas

Dónde se mostró

Alcance y volumen

Enriquecimiento

Paginación y orden

Cómo se ve una fila

`metadata` en este endpoint

Recetas

Relacionado

Referencia de Advertisement Search

Advertisement Insights

Filtros de actividad publicitaria

Enumeraciones y constantes

​Cuándo usarlo

​Fuentes

​Acotar a una empresa

​Filtros

​Fuente y formato

​Texto

​Fechas

​Dónde se mostró

​Alcance y volumen

​Enriquecimiento

​Paginación y orden

​Cómo se ve una fila

​metadata en este endpoint

​Recetas

​Relacionado

Referencia de Advertisement Search

Advertisement Insights

Filtros de actividad publicitaria

Enumeraciones y constantes

Cuándo usarlo

Fuentes

Acotar a una empresa

Filtros

Fuente y formato

Texto

Fechas

Dónde se mostró

Alcance y volumen

Enriquecimiento

Paginación y orden

Cómo se ve una fila

`metadata` en este endpoint

Recetas

Relacionado