Advertisement Search

Advertisement 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.

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. To find companies by their advertising rather than the ads themselves, use the advertisement_* filters on Company 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.
`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

{
  "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

"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

Competitor creatives in a market
High-reach LinkedIn ads
Instagram-only Meta ads

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
  }'

Each row’s companies.domain_search_id is a company spending heavily on LinkedIn in the US this month.

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
  }'