> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pubrio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Advertisement Search
> Encuentra los anuncios que una empresa está ejecutando en LinkedIn, Meta, Google, TikTok y Apple — por fuente, formato, país objetivo, alcance y ventana activa — y lee la creatividad, la página de destino y los datos de impresiones de cada uno.
[Advertisement Search](/es/api-reference/endpoint/companies/advertisements_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.
```bash theme={null}
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](/es/api-reference/endpoint/companies/advertisements_insights). Para encontrar *empresas* por su actividad publicitaria en lugar de los anuncios en sí, usa los filtros `advertisement_*` en [Company Search](/es/api-reference/endpoint/companies/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](/es/api-reference/enums#formats). |
| `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
```json theme={null}
{
"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
```json theme={null}
"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
```bash cURL theme={null}
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
}'
```
```bash cURL theme={null}
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.
```bash cURL theme={null}
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
Todos los parámetros y campos de respuesta.
Totales, niveles de alcance y creatividades de una empresa en una ventana de tiempo.
Encuentra empresas por su actividad publicitaria en Company Search.
Fuentes, formatos, plataformas y niveles de alcance.