> ## 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
> Find the ads a company is running across LinkedIn, Meta, Google, TikTok and Apple — by source, format, target country, reach and active window — and read the creative, landing page and impression data on each.
[Advertisement Search](/en/api-reference/endpoint/companies/advertisements_search) returns individual ads Pubrio has captured, one row per ad. Each row carries the creative (headline, image or video, landing page), where it was shown, when it ran, and the impression range the source reports.
```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
}'
```
## When to use it
* **Competitive creative research** — what a competitor is saying, in which countries, in which format.
* **Intent** — a company that just started advertising in a new market is expanding into it. Combine with `target_locations`.
* **Spend proxies** — `reach_tiers` and the `advertisement_*` metric filters rank companies by advertising volume without a spend figure.
For totals and trends use [Advertisement Insights](/en/api-reference/endpoint/companies/advertisements_insights). To find *companies* by their advertising rather than the ads themselves, use the `advertisement_*` filters on [Company Search](/en/api-reference/endpoint/companies/search).
## Sources
| `source_type` | Notes |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `linkedin` | Rich format labels (`Single Image Ad`, `Document Ad`, …) |
| `facebook` | Spans Facebook, Instagram, Messenger, Threads and Audience Network; narrow with `publisher_platforms`. `meta` is accepted as an alias. |
| `google` | Mostly `text` |
| `tiktok` | |
| `apple` | |
`total_impressions` is `null` on ads whose source publishes no estimate, and such ads never match `reach_tiers`.
## Scope to a company
| Key | Value |
| --------------- | --------------------------------------------- |
| `domains` | `["stripe.com"]` |
| `linkedin_urls` | `["https://www.linkedin.com/company/stripe"]` |
| `companies` | `["5378845d-…"]` — `domain_search_id` values |
A search without a company is allowed, for example `{"target_locations": ["SG"], "source_types": ["linkedin"]}`. Only ads already linked to a Pubrio company are returned unless you set `is_include_unlinked_companies: true`.
## Filters
### Source and format
| Key | Type | Matches |
| ----------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `source_types` | `string[]` | `linkedin`, `facebook`, `google`, `tiktok`, `apple`. Any listed. Unknown values match nothing and are echoed in `metadata.unsupported_source_types`. |
| `exclude_source_types` | `string[]` | Same vocabulary, excluded. |
| `advertisement_formats` | `string[]` | Canonical formats: `image`, `video`, `text`, `carousel`, `dynamic_product`, `document`, `message`, `event`, `article`, `spotlight`, `follow`, `job`, `engagement`. See [Formats](/en/api-reference/enums#formats). |
| `publisher_platforms` / `exclude_publisher_platforms` | `string[]` | `facebook`, `instagram`, `messenger`, `threads`, `audience_network`. Meta ads only. |
### Text
| Key | Type | Matches |
| ------------------------------ | --------------------- | -------------------------- |
| `headlines` | `string[]` | Headline text, any listed. |
| `search_term` / `search_terms` | `string` / `string[]` | Headline and description. |
### Dates
| Key | Type | Matches |
| -------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active_dates` | `[from, to]` | Ads **running at any point** in the window, including ads that started earlier and are still live. This is the window Advertisement Insights uses. Ads with no `started_at` count from `created_at`. Both dates required; UTC day boundaries. |
| `start_dates` | `[from, to]` | `started_at` inside the window — ads that *launched* then. Workspace-timezone day boundaries. |
| `end_dates` | `[from, to]` | `ended_at` inside the window. Workspace-timezone day boundaries. |
| `created_at` | date or ISO timestamp | Captured by Pubrio at or after this instant (UTC), for incremental sync. |
`start_dates` hides most of a company's running campaigns, because a campaign that launched in March is still running in August. Reach for `active_dates` unless you specifically want launches.
### Where it was shown
| Key | Type | Matches |
| -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `target_locations` | `string[]` | Countries the ad was delivered in. OR by default; add `{"key": "target_locations", "operator": "and"}` to `filter_conditions` to require every country. |
| `exclude_target_locations` | `string[]` | Countries to leave out. |
| `company_locations` | `string[]` | Headquarters country of the advertiser. |
### Reach and volume
| Key | Type | Matches |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `reach_tiers` | `string[]` | Impression band of the ad: `lt_1k`, `1k_10k`, `10k_50k`, `50k_100k`, `100k_500k`, `500k_1m`, `1m_plus`. Ads without a `total_impressions` value never match. |
| `advertisement_active_ads`, `advertisement_running_ads`, `advertisement_total_ads`, `advertisement_platform_count`, `advertisement_format_count`, `advertisement_impressions_estimate` | `[min, max]` | Filter ads by the **advertiser's** totals, e.g. `advertisement_active_ads: [10, null]` returns ads from companies with at least ten live ads. |
| `advertisement_country_activity` | object | `{ "country": "US", "rank": [null, 100] }` — ads from the top 100 advertisers in that country. |
### Enrichment
| Key | Type | Notes |
| ------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
| `is_realtime_enrichment` | `boolean` | If the search returns nothing, scrape the sources now and search again. Company-scoped searches only. |
| `enrichment_mode` | `default` / `latest` | `latest` re-scrapes on every call regardless of cache. |
| `is_include_unlinked_companies` | `boolean` | Also return ads Pubrio could not link to a company record (`is_company_matched: false`). |
### Paging and order
`per_page`, `page` and `is_ascending_order` behave as on every search. Rows are ordered by `created_at` (capture time), newest first.
## What a row looks like
```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` is `null` while the ad is still running.
* `advertisement_format` is the source's own label; `advertisement_format_normalized` is the slug you can filter on.
* `destination_url` is the unwrapped landing page; `raw_link_url` keeps the click-tracker exactly as captured.
* `total_impressions` is the source's text; the `_lower` / `_upper` pair is the parsed range.
### `metadata` on this 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" }]
}
```
| Key | When present | Meaning |
| -------------------------- | ------------------- | ------------------------------------------------------------------------------------------ |
| `ignored_fields` | Always | Body keys the endpoint dropped |
| `applied_source_types` | `source_types` sent | Values that were recognised |
| `unsupported_source_types` | Unknown value sent | Those values matched nothing |
| `coverage_notes` | When applicable | Coverage notes for the requested sources |
| `skipped_source_types` | When applicable | `[{ "source_type", "reason" }]` — sources not applied for the requested `target_locations` |
## Recipes
```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
}'
```
Each row's `companies.domain_search_id` is a company spending heavily on LinkedIn in the US this month.
```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
}'
```
## Related
Every parameter and response field.
Totals, reach tiers and creatives for one company over a window.
Find companies by their advertising on Company Search.
Sources, formats, platforms and reach tiers.