> ## 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.
# Busca de anúncios
> Encontre os anúncios que uma empresa está veiculando no LinkedIn, Meta, Google, TikTok e Apple — por fonte, formato, país-alvo, alcance e janela ativa — e leia os dados de criativo, landing page e impressões de cada um.
O [Advertisement Search](/pt/api-reference/endpoint/companies/advertisements_search) retorna anúncios individuais capturados pela Pubrio, uma linha por anúncio. Cada linha carrega o criativo (título, imagem ou vídeo, landing page), onde foi exibido, quando rodou e a faixa de impressões que a fonte relata.
```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
}'
```
## Quando usar
* **Pesquisa de criativos da concorrência** — o que um concorrente está dizendo, em quais países, em qual formato.
* **Intenção** — uma empresa que acabou de começar a anunciar em um novo mercado está se expandindo para lá. Combine com `target_locations`.
* **Proxies de investimento** — `reach_tiers` e os filtros de métrica `advertisement_*` ranqueiam empresas por volume de anúncios sem um valor de gasto.
Para totais e tendências, use [Advertisement Insights](/pt/api-reference/endpoint/companies/advertisements_insights). Para encontrar *empresas* pelos seus anúncios em vez dos anúncios em si, use os filtros `advertisement_*` no [Company Search](/pt/api-reference/endpoint/companies/search).
## Fontes
| `source_type` | Observações |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `linkedin` | Rótulos de formato ricos (`Single Image Ad`, `Document Ad`, …) |
| `facebook` | Abrange Facebook, Instagram, Messenger, Threads e Audience Network; restrinja com `publisher_platforms`. `meta` é aceito como alias. |
| `google` | Majoritariamente `text` |
| `tiktok` | |
| `apple` | |
`total_impressions` é `null` em anúncios cuja fonte não publica uma estimativa, e esses anúncios nunca correspondem a `reach_tiers`.
## Restringir a uma empresa
| Chave | Valor |
| --------------- | ------------------------------------------------ |
| `domains` | `["stripe.com"]` |
| `linkedin_urls` | `["https://www.linkedin.com/company/stripe"]` |
| `companies` | `["5378845d-…"]` — valores de `domain_search_id` |
Uma busca sem empresa é permitida, por exemplo `{"target_locations": ["SG"], "source_types": ["linkedin"]}`. Apenas anúncios já vinculados a uma empresa da Pubrio são retornados, a menos que você defina `is_include_unlinked_companies: true`.
## Filtros
### Fonte e formato
| Chave | Tipo | Corresponde a |
| ----------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_types` | `string[]` | `linkedin`, `facebook`, `google`, `tiktok`, `apple`. Qualquer um listado. Valores desconhecidos não correspondem a nada e são reproduzidos em `metadata.unsupported_source_types`. |
| `exclude_source_types` | `string[]` | Mesmo vocabulário, excluído. |
| `advertisement_formats` | `string[]` | Formatos canônicos: `image`, `video`, `text`, `carousel`, `dynamic_product`, `document`, `message`, `event`, `article`, `spotlight`, `follow`, `job`, `engagement`. Veja [Formatos](/pt/api-reference/enums#formats). |
| `publisher_platforms` / `exclude_publisher_platforms` | `string[]` | `facebook`, `instagram`, `messenger`, `threads`, `audience_network`. Apenas anúncios da Meta. |
### Texto
| Chave | Tipo | Corresponde a |
| ------------------------------ | --------------------- | ------------------------------------- |
| `headlines` | `string[]` | Texto do título, qualquer um listado. |
| `search_term` / `search_terms` | `string` / `string[]` | Título e descrição. |
### Datas
| Chave | Tipo | Corresponde a |
| -------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active_dates` | `[from, to]` | Anúncios **rodando em qualquer ponto** da janela, incluindo anúncios que começaram antes e ainda estão ativos. Esta é a janela que o Advertisement Insights usa. Anúncios sem `started_at` contam a partir de `created_at`. Ambas as datas são obrigatórias; limites de dia em UTC. |
| `start_dates` | `[from, to]` | `started_at` dentro da janela — anúncios que *começaram* naquele período. Limites de dia no fuso horário do workspace. |
| `end_dates` | `[from, to]` | `ended_at` dentro da janela. Limites de dia no fuso horário do workspace. |
| `created_at` | data ou timestamp ISO | Capturado pela Pubrio neste instante ou depois (UTC), para sincronização incremental. |
`start_dates` oculta a maioria das campanhas em andamento de uma empresa, porque uma campanha lançada em março ainda pode estar rodando em agosto. Recorra a `active_dates`, a menos que você queira especificamente os lançamentos.
### Onde foi exibido
| Chave | Tipo | Corresponde a |
| -------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target_locations` | `string[]` | Países onde o anúncio foi veiculado. OR por padrão; adicione `{"key": "target_locations", "operator": "and"}` a `filter_conditions` para exigir todos os países. |
| `exclude_target_locations` | `string[]` | Países a excluir. |
| `company_locations` | `string[]` | País da sede do anunciante. |
### Alcance e volume
| Chave | Tipo | Corresponde a |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reach_tiers` | `string[]` | Faixa de impressões do anúncio: `lt_1k`, `1k_10k`, `10k_50k`, `50k_100k`, `100k_500k`, `500k_1m`, `1m_plus`. Anúncios sem um valor de `total_impressions` nunca correspondem. |
| `advertisement_active_ads`, `advertisement_running_ads`, `advertisement_total_ads`, `advertisement_platform_count`, `advertisement_format_count`, `advertisement_impressions_estimate` | `[min, max]` | Filtra anúncios pelos totais do **anunciante**, ex.: `advertisement_active_ads: [10, null]` retorna anúncios de empresas com pelo menos dez anúncios ativos. |
| `advertisement_country_activity` | objeto | `{ "country": "US", "rank": [null, 100] }` — anúncios dos 100 maiores anunciantes naquele país. |
### Enriquecimento
| Chave | Tipo | Observações |
| ------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `is_realtime_enrichment` | `boolean` | Se a busca não retornar nada, faz scraping das fontes agora e busca novamente. Apenas buscas restritas a uma empresa. |
| `enrichment_mode` | `default` / `latest` | `latest` refaz o scraping em toda chamada, independentemente do cache. |
| `is_include_unlinked_companies` | `boolean` | Também retorna anúncios que a Pubrio não conseguiu vincular a um registro de empresa (`is_company_matched: false`). |
### Paginação e ordem
`per_page`, `page` e `is_ascending_order` funcionam como em qualquer busca. As linhas são ordenadas por `created_at` (momento de captura), das mais recentes para as mais antigas.
## Como é uma linha
```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` é `null` enquanto o anúncio ainda está rodando.
* `advertisement_format` é o rótulo próprio da fonte; `advertisement_format_normalized` é o slug pelo qual você pode filtrar.
* `destination_url` é a landing page desembrulhada; `raw_link_url` mantém o rastreador de cliques exatamente como capturado.
* `total_impressions` é o texto da fonte; o par `_lower` / `_upper` é a faixa interpretada.
### `metadata` neste 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" }]
}
```
| Chave | Quando presente | Significado |
| -------------------------- | -------------------------- | --------------------------------------------------------------------------------------------- |
| `ignored_fields` | Sempre | Chaves do corpo que o endpoint descartou |
| `applied_source_types` | `source_types` enviado | Valores que foram reconhecidos |
| `unsupported_source_types` | Valor desconhecido enviado | Esses valores não corresponderam a nada |
| `coverage_notes` | Quando aplicável | Notas de cobertura para as fontes solicitadas |
| `skipped_source_types` | Quando aplicável | `[{ "source_type", "reason" }]` — fontes não aplicadas para os `target_locations` solicitados |
## Receitas
```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
}'
```
O `companies.domain_search_id` de cada linha é uma empresa investindo pesado no LinkedIn nos EUA neste mês.
```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
}'
```
## Relacionados
Todos os parâmetros e campos de resposta.
Totais, faixas de alcance e criativos de uma empresa em uma janela de tempo.
Encontre empresas pelos seus anúncios no Company Search.
Fontes, formatos, plataformas e faixas de alcance.