{"uid":"cap_VR0Q_C8PyTPOD_HWB6gb4","slug":"agents-pubrio-com-search-for-company-advertisements-2f77b8e5","name":"Search for Company Advertisements","description":"Search advertisements run by companies. See the [Advertisement Search guide](/en/developer-guides/search/advertisement-search).","url":"https://agents.pubrio.com/companies/advertisements/search?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"page":{"type":"integer","default":1,"example":1,"description":"Page number, starting at 1. The ceiling is your subscription's `max_search_page` (`max_company_search_page` for company search), returned by [Profile](/en/api-reference/endpoint/profile/profile). Exceeding it returns **HTTP 416**."},"query":{"type":"string"},"domains":{"type":"array","items":{"type":"string"},"example":["pubrio.com"],"description":"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."},"filters":{"type":"object","properties":{"source_types":{"type":"array","items":{"enum":["linkedin","facebook","google","tiktok","apple"],"type":"string"}},"advertisement_formats":{"type":"array","items":{"enum":["image","video","text","carousel","dynamic_product","document","message","event","article","spotlight","follow","job","engagement","other"],"type":"string"}}}},"per_page":{"type":"integer","default":25,"example":25,"maximum":25,"description":"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](/en/api-reference/endpoint/profile/profile). Exceeding it returns **HTTP 416** with code `41676` (or `41613` on company and people search), not a clamped result set."},"companies":{"type":"array","items":{"type":"string","format":"uuid"},"description":"A list of unique identifiers (domain_search_id) used for company and people search operations."},"end_dates":{"type":"array","items":{"type":"string","format":"date"},"example":["2025-12-25","2025-12-25"],"description":"A list of end dates to filter search results."},"headlines":{"type":"array","items":{"type":"string"},"example":["ASUS","iPhone"],"description":"A list of headlines to filter search results."},"created_at":{"type":"string","format":"date-time","example":"2026-09-02T12:00:00Z","description":"Ingested at or after this instant (UTC). Date or ISO timestamp. For incremental syncs pass the `created_at` of your newest stored row."},"reach_tiers":{"type":"array","items":{"enum":["lt_1k","1k_10k","10k_50k","50k_100k","100k_500k","500k_1m","1m_plus"],"type":"string"},"example":["100k_500k","500k_1m","1m_plus"],"description":"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."},"search_term":{"type":"string"},"start_dates":{"type":"array","items":{"type":"string","format":"date"},"example":["2025-12-01","2025-12-01"],"description":"A list of start dates to filter search results."},"active_dates":{"type":"array","items":{"type":"string","format":"date"},"example":["2026-08-01","2026-08-31"],"maxItems":2,"minItems":2,"description":"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`."},"search_terms":{"type":"array","items":{"type":"string"},"example":["pubrio"],"description":"A list of strings over which we want to filter the results."},"source_types":{"type":"array","items":{"enum":["linkedin","facebook","google","tiktok","apple"],"type":"string"},"example":["linkedin","facebook"],"description":"Sources to include: `linkedin`, `facebook` (`meta` accepted), `google`, `tiktok`, `apple`. Unknown values match nothing and are echoed in `metadata.unsupported_source_types`."},"linkedin_urls":{"type":"array","items":{"type":"string"},"example":["https://www.linkedin.com/company/pubrio"],"description":"The fully formed URL of the LinkedIn company profile. URL begin with `http` and contain `linkedin.com/company/`"},"enrichment_mode":{"enum":["default","latest"],"type":"string","default":"default","example":"latest","description":"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."},"target_locations":{"type":"array","items":{"type":"string"},"example":["TW","AE","NO"],"description":"Country codes the results must target. Combines with `filter_conditions` as OR by default — a result matches if it targets any of them."},"company_locations":{"type":"array","items":{"type":"string"},"example":["US","SG","CN"],"description":"The location of the company headquarters. Check out `location` endpoints under the Filters tab for more information."},"filter_conditions":{"type":"array","items":{"type":"object","properties":{"key":{"enum":["target_locations","publisher_platforms"],"type":"string","example":"target_locations","description":"The filter key specifying which property to apply the operator to."},"operator":{"enum":["or","and"],"type":"string","example":"or","description":"The logical operator to apply. Use 'or' to match advertisements carrying any of the listed values, or 'and' to require all of them."}}},"description":"Advanced filtering options for advertisement searches. Specify conditions to refine your search results for the ads search endpoint."},"is_ascending_order":{"type":"boolean","default":false,"example":false,"description":"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."},"publisher_platforms":{"type":"array","items":{"enum":["facebook","instagram","messenger","threads","audience_network"],"type":"string"},"example":["facebook","instagram"],"description":"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)."},"exclude_source_types":{"type":"array","items":{"enum":["linkedin","facebook","google","tiktok","apple"],"type":"string"},"example":["apple"],"description":"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."},"advertisement_formats":{"type":"array","items":{"enum":["image","video","text","carousel","dynamic_product","document","message","event","article","spotlight","follow","job","engagement"],"type":"string"},"example":["image","video"],"description":"Find companies with at least one advertisement in any of these creative formats."},"is_realtime_enrichment":{"type":"boolean","default":false,"example":true,"description":"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."},"advertisement_search_id":{"type":"string","allOf":[{"type":"string","format":"uuid","example":"a92643e8-9033-4029-aa65-ef929327cebb","description":"A unique identifier for the advertisement search result. Used to reference specific advertisements returned from the ads search endpoint."}],"example":"a92643e8-9033-4029-aa65-ef929327cebb","description":"Return only this one record. Handy for re-fetching a row you stored earlier without paging."},"advertisement_total_ads":{"type":"array","items":{"type":"integer","nullable":true},"example":[10,null],"maxItems":2,"minItems":2,"description":"Minimum and maximum count of the company's total advertisements ever recorded, across all countries."},"advertisement_active_ads":{"type":"array","items":{"type":"integer","nullable":true},"example":[1,null],"maxItems":2,"minItems":2,"description":"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\"."},"exclude_target_locations":{"type":"array","items":{"type":"string"},"example":["IS","GB","FR","IE","ES"],"description":"Country codes the results must not target. Combines with `filter_conditions` as OR by default — a result matches if it targets any of them."},"advertisement_running_ads":{"type":"array","items":{"type":"integer","nullable":true},"example":[1,null],"maxItems":2,"minItems":2,"description":"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."},"advertisement_format_count":{"type":"array","items":{"type":"integer","nullable":true},"example":[2,null],"maxItems":2,"minItems":2,"description":"Minimum and maximum number of distinct advertisement creative formats the company is actively running."},"exclude_publisher_platforms":{"type":"array","items":{"enum":["facebook","instagram","messenger","threads","audience_network"],"type":"string"},"example":["audience_network"],"description":"Exclude Facebook/Meta ads delivered on these platform surfaces."},"advertisement_platform_count":{"type":"array","items":{"type":"integer","nullable":true},"example":[2,null],"maxItems":2,"minItems":2,"description":"Minimum and maximum number of distinct ad platforms (linkedin, facebook, google, tiktok, apple) the company is actively advertising on."},"is_include_unlinked_companies":{"type":"boolean","default":false,"example":true,"description":"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."},"advertisement_country_activity":{"type":"object","example":{"rank":[null,500],"country":"US"},"required":["country"],"properties":{"rank":{"type":"array","items":{"type":"integer","nullable":true},"example":[null,500],"maxItems":2,"minItems":2,"description":"Rank within that country by advertising volume. 1 is the biggest spender, and the number increases as advertising volume decreases. Use `[null, 500]` to find the top 500 biggest spenders in that country; use `[500, null]` to find everyone ranked 500th or lower."},"country":{"type":"string","example":"US","description":"ISO 3166-1 alpha-2 country code to scope this filter to. Required."},"last_seen":{"type":"array","items":{"type":"string","format":"date","nullable":true},"example":["2026-07-01",null],"maxItems":2,"minItems":2,"description":"[from, to] window for when the company's most recent ad in this country ran, for the opposite question: who has gone quiet in a market."},"total_ads":{"type":"array","items":{"type":"integer","nullable":true},"example":[10,null],"maxItems":2,"minItems":2,"description":"Minimum and maximum total advertisements, scoped to this country."},"active_ads":{"type":"array","items":{"type":"integer","nullable":true},"example":[1,null],"maxItems":2,"minItems":2,"description":"Minimum and maximum active advertisements, scoped to this country."},"first_seen":{"type":"array","items":{"type":"string","format":"date","nullable":true},"example":["2026-07-01",null],"maxItems":2,"minItems":2,"description":"[from, to] window for when the company's earliest ad in this country ran — the \"newly entered this market\" filter. Either bound may be null for an open-ended window; dates use the request timezone. A company whose ads carry no start date has no first-seen value and is never reported as new."},"percentile":{"type":"array","items":{"type":"number","nullable":true},"example":[90,null],"maxItems":2,"minItems":2,"description":"Percentile within that country by advertising volume, 0-100. Higher means a bigger spender. Use `[90, null]` for the top 10% of spenders in that country."},"impressions":{"type":"array","items":{"type":"integer","nullable":true},"example":[1000,null],"maxItems":2,"minItems":2,"description":"Minimum and maximum estimated impressions, scoped to this country."},"running_ads":{"type":"array","items":{"type":"integer","nullable":true},"example":[1,null],"maxItems":2,"minItems":2,"description":"Minimum and maximum running advertisements, scoped to this country. Currently populated for LinkedIn ads only."},"volume_score":{"type":"array","items":{"type":"number","nullable":true},"example":[0.5,null],"maxItems":2,"minItems":2,"description":"The underlying 0-1 advertising volume score that `rank` and `percentile` are both computed from."}},"description":"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."},"advertisement_impressions_estimate":{"type":"array","items":{"type":"integer","nullable":true},"example":[1000,null],"maxItems":2,"minItems":2,"description":"Minimum and maximum estimated advertisement impressions, summed across all countries. Only advertisements with a reported impression range are counted."}}},"responseSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"pagination":{"type":"object","properties":{"page":{"type":"integer","description":"Current page number."},"per_page":{"type":"integer","description":"Records per page."},"is_timeout":{"type":"boolean","description":"`true` when the search ran out of time. `total_entries` then only counts the rows returned so far, and an empty page means the search did not finish, not that nothing matched."},"total_pages":{"type":"integer","description":"`total_entries` divided by `per_page`."},"is_estimated":{"type":"boolean","description":"`true` when `total_entries` is an estimate rather than an exact count. Do not use an estimated total to decide when to stop paging; stop when a page returns fewer rows than `per_page`."},"total_entries":{"type":"integer","description":"Total matching records. An estimate when `is_estimated` is `true`."},"total_display_pages":{"type":"integer","description":"Page count for this result, capped by your plan's `max_display_search_page`."}},"description":"Pagination for the result set."},"advertisements":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","nullable":true,"description":"Headline or ad title."},"ended_at":{"type":"string","format":"date-time","nullable":true,"description":"When the ad stopped running; `null` while it is still running."},"companies":{"type":"object","properties":{"domain":{"type":"string","description":"Company domain, normalised (`stripe.com`)."},"logo_url":{"type":"string","nullable":true,"description":"Company logo URL."},"company_url":{"type":"string","nullable":true,"description":"Company website URL."},"company_name":{"type":"string","description":"Company name."},"country_code":{"type":"string","nullable":true,"description":"ISO 3166-1 alpha-2 code of the company headquarters."},"linkedin_name":{"type":"string","nullable":true,"description":"LinkedIn company slug (the part after `linkedin.com/company/`)."},"domain_search_id":{"type":"string","format":"uuid","description":"Pubrio company identifier. Pass it to `companies` on any search, or to Company Lookup."}},"description":"The company the record is linked to."},"image_url":{"type":"string","nullable":true,"description":"Creative image, when the ad has one."},"video_url":{"type":"string","nullable":true,"description":"Creative video, when the ad has one."},"advertiser":{"type":"string","nullable":true,"description":"Advertiser name as shown by the source."},"created_at":{"type":"string","format":"date-time","description":"When Pubrio first captured the ad. This is the default sort key."},"started_at":{"type":"string","format":"date-time","nullable":true,"description":"When the ad started running, as reported by the source."},"source_type":{"enum":["linkedin","facebook","google","tiktok","apple"],"type":"string","description":"Source the ad was captured from. Same vocabulary as the `source_types` filter."},"raw_link_url":{"type":"string","nullable":true,"description":"The original link exactly as captured, before unwrapping."},"last_modified":{"type":"string","format":"date-time","description":"When the record was last updated."},"advertiser_url":{"type":"string","nullable":true,"description":"Advertiser page at the source, when available."},"carousel_images":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Carousel frames, for carousel formats."},"destination_url":{"type":"string","nullable":true,"description":"Resolved landing page. Facebook click-wrappers such as `fb.me` are unwrapped to the real funnel URL."},"advertisement_id":{"type":"string","format":"uuid","description":"Advertisement identifier."},"advertisement_url":{"type":"string","nullable":true,"description":"Link to the ad in the source's ad library, when available."},"total_impressions":{"type":"string","nullable":true,"description":"Impression estimate exactly as the source publishes it, e.g. `< 1k`, `10k-50k`. `null` for sources that do not report impressions."},"is_company_matched":{"type":"boolean","description":"`true` when the ad is linked to a Pubrio company record. Unlinked ads are returned only with `is_include_unlinked_companies: true`."},"publisher_platforms":{"type":"array","items":{"enum":["facebook","instagram","messenger","threads","audience_network"],"type":"string"},"nullable":true,"description":"Meta surfaces the ad ran on: `facebook`, `instagram`, `messenger`, `threads`, `audience_network`. `null` for non-`facebook` sources."},"advertisement_format":{"type":"string","nullable":true,"description":"Format label exactly as the source publishes it, e.g. `Single Image Ad`, `MULTI_IMAGES`."},"target_country_codes":{"type":"array","items":{"type":"string"},"nullable":true,"description":"Countries the ad was shown in (ISO 3166-1 alpha-2). Same vocabulary as the `target_locations` filter."},"advertisement_search_id":{"type":"string","format":"uuid","description":"Same value as `advertisement_id`. Pass it to Advertisement Lookup."},"total_impressions_lower":{"type":"integer","nullable":true,"description":"Lower bound of the impression range; `null` for `< N` ranges."},"total_impressions_upper":{"type":"integer","nullable":true,"description":"Upper bound of the impression range; `null` for open-ended ranges."},"advertisement_format_normalized":{"enum":["image","video","text","carousel","dynamic_product","document","message","event","article","spotlight","follow","job","engagement","other"],"type":"string","nullable":true,"description":"Canonical format, the vocabulary the `advertisement_formats` filter accepts. `other` when the raw label is not mapped."}},"description":"One advertisement."}}}},"metadata":{"allOf":[{"type":"object","properties":{"filters":{"type":"object","description":"Echo of the request body as the endpoint applied it, including defaults such as `per_page` and `language`."},"profile":{"type":"object","nullable":true,"description":"Credit block (`credit`, `topup_credit`, `total_credit_cost`) when credit accounting is requested; `null` on plain API-key traffic."},"ignored_fields":{"type":"array","items":{"type":"string"},"description":"Body keys the endpoint did not recognise and dropped. Empty means every key applied — a misspelled filter widens the search instead of failing."}},"description":"Request context."},{"type":"object","properties":{"coverage_notes":{"type":"array","items":{"type":"object","properties":{"scope":{"enum":["eea_uk_ch"],"type":"string"},"source_type":{"type":"string"}}},"description":"Coverage notes for the requested sources, when applicable."},"applied_source_types":{"type":"array","items":{"type":"string"},"description":"Only when `source_types` was sent: the values that were recognised and applied."},"skipped_source_types":{"type":"array","items":{"type":"object","properties":{"reason":{"enum":["country_unknown_until_enriched"],"type":"string","description":"Why the source was not applied."},"source_type":{"type":"string","description":"Source that was skipped."}}},"description":"Sources that were not applied for the requested `target_locations`, each with a `reason`."},"unsupported_source_types":{"type":"array","items":{"type":"string"},"description":"Only when `source_types` contained a value that is not a known source. Those values match nothing."}}}],"description":"Request context."}}},"example":null,"exampleRequest":null,"tags":[],"displayCostAmount":"unknown","displayCostAsset":"USD","priceDynamic":true,"priceHint":null,"priceStatus":"unknown_unparsed","priceSource":"registry","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"unknown","summary":"price unknown","primary":{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"},"accepted":[{"kind":"dynamic","protocol":"mpp","network":"tempo","amountUsd":null,"per":"call","confidence":"unknown"}]},"paymentMethods":[{"uid":"pm_krFraR7c33VxEisrE8d8t","protocol":"mpp","methodType":"crypto","chain":"tempo","mode":"charge","costAmount":"unknown","costPer":"request","priority":0,"asset":null,"unit":"request","depositMicros":null,"planRef":null}],"brandName":"agents.pubrio.com","brandSlug":"agents-pubrio-com-x402","brandBaseUrl":"https://agents.pubrio.com","brandDocsUrl":null,"whatItDoes":"Search and filter advertisements run by companies across platforms like LinkedIn, Facebook, Google, TikTok, and Apple, with filters for format, date range, and headlines.","exampleAgentPrompt":"Search Pubrio for all LinkedIn and Facebook video and image ads currently running by Stripe — show me 25 results starting from page 1.","exampleUseCases":[{"title":"Competitor ad strategy research","prompt":"Find all the ads that Salesforce is running on LinkedIn and Google right now — I want to see what formats they're using and what their headlines look like. Show me 25 per page."},{"title":"Market expansion signal detection","prompt":"Search for ads by companies with domains shopify.com and bigcommerce.com on Facebook and TikTok that ended after January 1, 2025 — I want to see if they're pushing into new markets."},{"title":"Industry ad format benchmarking","prompt":"Look up carousel and video ads across these companies — hubspot.com, marketo.com, and mailchimp.com — so I can benchmark what ad formats B2B SaaS companies are using on LinkedIn."}],"resultDescription":"Returns a paginated list of advertisements with fields including ad title, start/end dates, source platform, format type, and associated company details (name, domain, logo URL, LinkedIn slug, country code). Pagination metadata includes total entries, estimated counts, timeout flags, and page limits based on the subscription plan.","failureModes":["HTTP 416 if page exceeds subscription's max_search_page limit","HTTP 416 with code 41613 if per_page exceeds subscription's max_search_per_page","Empty result set if no ads match the specified filters or company identifiers","Timeout indicated by is_timeout: true in pagination, with partial results","Invalid UUID format for companies array returns validation error","Unsupported source_type or advertisement_format enum value returns error"],"whenToPreferThis":"Use this endpoint when you need to search across multiple companies' advertisements with flexible filtering by platform, format, date range, or headline keyword. Prefer this over the single-company advertisement lookup when you don't already have a specific advertisement search ID, or when you want to compare advertising activity across multiple companies simultaneously. Best suited for competitive intelligence, market research, and monitoring campaigns at scale.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-11T12:46:43.572Z","isFirstParty":false,"canonicalSlug":"agents-pubrio-com-search-for-company-advertisements-2f77b8e5"}