Skip to main content
POST
Search for company advertisements

Authorizations

​
pubrio-api-key
string
header
required

A unique API token that represents the actions you perform through the API and the corresponding permissions and operations. You can create it through the Settings section.

Body

application/json
​
target_locations
string[]

Country codes the results must target. Combines with filter_conditions as OR by default — a result matches if it targets any of them.

Example:
​
exclude_target_locations
string[]

Country codes the results must not target. Combines with filter_conditions as OR by default — a result matches if it targets any of them.

Example:
​
search_terms
string[]

A list of strings over which we want to filter the results.

Example:
​
headlines
string[]

A list of headlines to filter search results.

Example:
​
filter_conditions
object[]

Advanced filtering options for advertisement searches. Specify conditions to refine your search results for the ads search endpoint.

​
start_dates
string<date>[]

A list of start dates to filter search results.

Example:
​
end_dates
string<date>[]

A list of end dates to filter search results.

Example:
​
active_dates
string<date>[]

Inclusive [from, to] window (UTC). Returns ads running at any point in it, including ones that started earlier, so it reconciles with Advertisement Insights. Undated ads count from created_at. Both dates required, from ≤ to.

Required array length: 2 elements
Example:
​
created_at
string<date-time>

Ingested at or after this instant (UTC). Date or ISO timestamp. For incremental syncs pass the created_at of your newest stored row.

Example:

"2026-09-02T12:00:00Z"

​
company_locations
string[]

The location of the company headquarters. Check out location endpoints under the Filters tab for more information.

Example:
​
companies
string<uuid>[]

A list of unique identifiers (domain_search_id) used for company and people search operations.

​
advertisement_search_id
string<uuid>

Return only this one record. Handy for re-fetching a row you stored earlier without paging.

Example:

"a92643e8-9033-4029-aa65-ef929327cebb"

​
domains
string[]

List of company domains used for company and people search operations. If we receive a URL such as www.pubrio.com or https://docs.pubrio.com/, the system will convert it to pubrio.com for processing.

Example:
​
linkedin_urls
string[]

The fully formed URL of the LinkedIn company profile. URL begin with http and contain linkedin.com/company/

Example:
​
is_realtime_enrichment
boolean
default:false

Opt into realtime enrichment for a single, company-scoped query (filtered by domain_search_id, domains, or linkedin_urls). When the initial search returns zero results, the endpoint scrapes the source, persists the records, and re-runs the search before responding. Subject to a per-route deadline.

Example:

true

​
advertisement_formats
enum<string>[]

Find companies with at least one advertisement in any of these creative formats.

Available options:
image,
video,
text,
carousel,
dynamic_product,
document,
message,
event,
article,
spotlight,
follow,
job,
engagement
Example:
​
reach_tiers
enum<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; unknown slugs match nothing.

Available options:
lt_1k,
1k_10k,
10k_50k,
50k_100k,
100k_500k,
500k_1m,
1m_plus
Example:
​
advertisement_active_ads
(integer | null)[]

Minimum and maximum count of the company's currently active advertisements, across all countries. Use null for an open-ended bound, e.g. [1, null] for "at least one active ad".

Required array length: 2 elements
Example:
​
advertisement_running_ads
(integer | null)[]

Minimum and maximum count of the company's advertisements that are still running (no end date, or an end date in the future). Currently populated for LinkedIn ads only.

Required array length: 2 elements
Example:
​
advertisement_total_ads
(integer | null)[]

Minimum and maximum count of the company's total advertisements ever recorded, across all countries.

Required array length: 2 elements
Example:
​
advertisement_platform_count
(integer | null)[]

Minimum and maximum number of distinct ad platforms (linkedin, facebook, google, tiktok, apple) the company is actively advertising on.

Required array length: 2 elements
Example:
​
advertisement_format_count
(integer | null)[]

Minimum and maximum number of distinct advertisement creative formats the company is actively running.

Required array length: 2 elements
Example:
​
advertisement_impressions_estimate
(integer | null)[]

Minimum and maximum estimated advertisement impressions, summed across all countries. Only advertisements with a reported impression range are counted.

Required array length: 2 elements
Example:
​
advertisement_country_activity
object

Advertising activity for one specific country. country is required, and at least one other field must be set (a country by itself matches nothing). For an all-country total instead, use the top-level advertisement_active_ads / advertisement_total_ads / advertisement_impressions_estimate filters.

Example:
​
source_types
enum<string>[]

Sources to include: linkedin, facebook (meta accepted), google, tiktok, apple. Unknown values match nothing and are echoed in metadata.unsupported_source_types.

Available options:
linkedin,
facebook,
google,
tiktok,
apple
Example:
​
exclude_source_types
enum<string>[]

Exclude ads captured from these sources. Same vocabulary as source_types (linkedin, facebook, google, tiktok, apple; meta is an alias of facebook). Unknown values are ignored.

Available options:
linkedin,
facebook,
google,
tiktok,
apple
Example:
​
enrichment_mode
enum<string>
default:default

Controls realtime enrichment behavior. default returns whatever is already in the database, and triggers enrichment only when the result set is empty and is_realtime_enrichment is set. latest bypasses the cache and forces a re-enrichment pass against the freshest source records on every call — it triggers enrichment on its own without needing any other flag.

Available options:
default,
latest
Example:

"latest"

​
per_page
integer
default:25

Records per page. Defaults to 25, which is also the ceiling on most plans — the limit is your subscription's max_search_per_page, returned by Profile. Exceeding it returns HTTP 416 with code 41676 (or 41613 on company and people search), not a clamped result set.

Required range: x <= 25
Example:

25

​
page
integer
default:1

Page number, starting at 1. The ceiling is your subscription's max_search_page (max_company_search_page for company search), returned by Profile. Exceeding it returns HTTP 416.

Example:

1

​
is_ascending_order
boolean
default:false

Sort direction. Results are returned newest-first by default; set true for oldest-first. There is no sort_by on this endpoint — the sort key is fixed and stated in the endpoint description.

Example:

false

​
publisher_platforms
enum<string>[]

Filter Facebook/Meta ads by the platform surface they were delivered on. Lowercase and case-insensitive. Only applies to the facebook source (other sources are single-platform).

Available options:
facebook,
instagram,
messenger,
threads,
audience_network
Example:
​
exclude_publisher_platforms
enum<string>[]

Exclude Facebook/Meta ads delivered on these platform surfaces.

Available options:
facebook,
instagram,
messenger,
threads,
audience_network
Example:
​
is_include_unlinked_companies
boolean
default:false

Include ads not yet linked to a resolved company (raw-layer ads, e.g. scam or burner-page ads). Defaults to false, which returns only company-attributed ads.

Example:

true

Response

Successful response containing company advertisement search details.

​
metadata
object

Request context.

​
data
object
Last modified on March 3, 2026