> ## 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. # Company Search > Search the Pubrio database for companies matching specified criteria such as industry, size, location, and technologies. ## OpenAPI ````yaml en-openapi POST /companies/search openapi: 3.0.0 info: description: >- The Pubrio API delivers market expansion intelligence — real-time signals that flag when a company enters a new market — alongside the company and people data beneath them. Search, look up, and enrich accounts and contacts, and subscribe to typed, dated movement signals across 200+ markets. version: 1.0.0 title: Pubrio OpenAPI termsOfService: https://pubrio.com/en/terms-of-service contact: email: king.lai@pubrio.com name: King Lai url: https://pubrio.com/en/get-in-touch license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://api.pubrio.com security: - pubrio_api_key: [] tags: - name: Profile description: Workspace profile information and usage statistics - name: Enrichment description: Enrich people and company records with detailed B2B data - name: Lookalike description: Find companies similar to a given company - name: Search description: Search for people, companies, jobs, news, and advertisements with filters - name: Lookup description: >- Look up detailed information for specific people, companies, jobs, news, advertisements, and technologies - name: LinkedIn description: Look up people and company data via LinkedIn profile URLs - name: Redeem description: Redeem credits to unlock people contact details (single and batch) - name: Channels description: Manage outreach channel templates (create, update, delete, list) - name: Monitor description: Create and manage data monitors with webhooks, statistics, and processing - name: Filters description: >- Retrieve available filter values for search parameters (technologies, locations, verticals, etc.) - name: API Keys description: List and inspect API request logs and usage analytics for API keys - name: Insights description: Aggregated signal insights for companies (jobs, news, advertisements). - name: Export description: Bulk data exports (credit-gated). - name: Expansion description: >- Company market-expansion intelligence: signals, stages, markets, and exports. externalDocs: description: >- The Pubrio API is used to search, preview and enrich Contacts and Accounts. Pubrio database provides extensive B2B contacts and sales intelligence data. url: https://docs.pubrio.com paths: /companies/search: post: tags: - Search summary: Search for companies description: >- Search the Pubrio database for companies matching specified criteria such as industry, size, location, and technologies. operationId: companies_search parameters: [] requestBody: required: true content: application/json: schema: type: object properties: company_name: $ref: '#/components/schemas/company_name' companies: $ref: '#/components/schemas/companies' domains: $ref: '#/components/schemas/domains' linkedin_urls: $ref: '#/components/schemas/company_linkedin_urls' company_filters: $ref: '#/components/schemas/company_filters' locations: $ref: '#/components/schemas/locations' exclude_locations: $ref: '#/components/schemas/exclude_locations' places: $ref: '#/components/schemas/places' exclude_places: $ref: '#/components/schemas/exclude_places' job_locations: $ref: '#/components/schemas/locations' job_exclude_locations: $ref: '#/components/schemas/job_exclude_locations' job_posted_dates: $ref: '#/components/schemas/posted_dates' job_titles: $ref: '#/components/schemas/people_titles' verticals: $ref: '#/components/schemas/verticals' vertical_categories: $ref: '#/components/schemas/vertical_categories' vertical_sub_categories: $ref: '#/components/schemas/vertical_sub_categories' categories: $ref: '#/components/schemas/categories' technologies: $ref: '#/components/schemas/technologies' employees: $ref: '#/components/schemas/employees' revenues: $ref: '#/components/schemas/revenues' founded_dates: $ref: '#/components/schemas/founded_dates' keywords: $ref: '#/components/schemas/keywords' social_media: $ref: '#/components/schemas/company_social_media' news_categories: $ref: '#/components/schemas/news_categories' news_published_dates: $ref: '#/components/schemas/published_dates' advertisement_search_terms: $ref: '#/components/schemas/advertisement_search_terms' advertisement_target_locations: $ref: '#/components/schemas/advertisement_target_locations' advertisement_exclude_target_locations: $ref: '#/components/schemas/advertisement_exclude_target_locations' advertisement_start_dates: $ref: '#/components/schemas/advertisement_start_dates' advertisement_end_dates: $ref: '#/components/schemas/advertisement_end_dates' advertisement_active_dates: $ref: '#/components/schemas/advertisement_active_dates' advertisement_status: $ref: '#/components/schemas/advertisement_status' advertisement_headlines: $ref: '#/components/schemas/advertisement_headlines' advertisement_platforms: $ref: '#/components/schemas/advertisement_platforms' advertisement_publisher_platforms: $ref: '#/components/schemas/advertisement_publisher_platforms' advertisement_exclude_publisher_platforms: $ref: >- #/components/schemas/advertisement_exclude_publisher_platforms advertisement_formats: $ref: '#/components/schemas/advertisement_formats' advertisement_active_ads: $ref: '#/components/schemas/advertisement_active_ads' advertisement_running_ads: $ref: '#/components/schemas/advertisement_running_ads' advertisement_total_ads: $ref: '#/components/schemas/advertisement_total_ads' advertisement_platform_count: $ref: '#/components/schemas/advertisement_platform_count' advertisement_format_count: $ref: '#/components/schemas/advertisement_format_count' advertisement_impressions_estimate: $ref: '#/components/schemas/advertisement_impressions_estimate' advertisement_country_activity: $ref: '#/components/schemas/advertisement_country_activity' sort_by: $ref: '#/components/schemas/company_sort_by' is_ascending_order: type: boolean example: true description: >- Direction for `sort_by`. Defaults to ascending, which for `advertisement_country_rank` means the biggest advertisers first. filter_conditions: $ref: '#/components/schemas/company_filter_conditions' is_enable_similarity_search: $ref: '#/components/schemas/is_enable_similarity_search' similarity_score: $ref: '#/components/schemas/similarity_score' exclude_fields: $ref: '#/components/schemas/exclude_fields' is_parameter_metadata_available: $ref: '#/components/schemas/is_parameter_metadata_available' is_profile_metadata_available: $ref: '#/components/schemas/is_profile_metadata_available' per_page: $ref: '#/components/schemas/per_page' page: $ref: '#/components/schemas/page' cloud_footprint_providers: $ref: '#/components/schemas/cloud_footprint_providers' cloud_footprint_exclude_providers: $ref: '#/components/schemas/exclude_providers' cloud_footprint_target_locations: $ref: '#/components/schemas/cloud_footprint_target_locations' cloud_footprint_exclude_target_locations: $ref: >- #/components/schemas/cloud_footprint_exclude_target_locations cloud_footprint_cloud_regions: $ref: '#/components/schemas/cloud_regions' cloud_footprint_exclude_cloud_regions: $ref: '#/components/schemas/exclude_cloud_regions' cloud_footprint_cities: $ref: '#/components/schemas/cities' cloud_footprint_exclude_cities: $ref: '#/components/schemas/exclude_cities' cloud_footprint_first_seen_dates: $ref: '#/components/schemas/first_seen_dates' cloud_footprint_last_seen_dates: $ref: '#/components/schemas/last_seen_dates' cloud_footprint_is_cross_border_only: $ref: '#/components/schemas/is_cross_border_only' cloud_footprint_host_count: $ref: '#/components/schemas/cloud_footprint_host_count' cloud_footprint_server_count: $ref: '#/components/schemas/cloud_footprint_server_count' cloud_footprint_shared_server_count: $ref: '#/components/schemas/cloud_footprint_shared_server_count' cloud_footprint_provider_count: $ref: '#/components/schemas/cloud_footprint_provider_count' cloud_footprint_country_count: $ref: '#/components/schemas/cloud_footprint_country_count' cloud_footprint_cross_border_country_count: $ref: >- #/components/schemas/cloud_footprint_cross_border_country_count cloud_footprint_region_count: $ref: '#/components/schemas/cloud_footprint_region_count' cloud_footprint_city_count: $ref: '#/components/schemas/cloud_footprint_city_count' cloud_footprint_primary_provider: $ref: '#/components/schemas/cloud_footprint_primary_provider' cloud_footprint_country_activity: $ref: '#/components/schemas/cloud_footprint_country_activity' responses: '200': description: Successful response containing company search details. content: application/json: schema: type: object properties: metadata: type: object description: >- Request context: `recent_search_log_identifier`, echoed `parameters` and `filters`, an optional `profile` credit block, and `ignored_fields` (body keys the endpoint dropped). data: $ref: '#/components/schemas/data' example: data: pagination: page: 1 per_page: 25 total_entries: 45234700 total_pages: 1809388 companies: - logo_url: >- https://buckets.pubrio.com/company-logo/MjI0NDc1OTMxaWxqOXNzbmoxdHdpdHRlci5jb20=.jpg company_name: Twitter emails: - ... phones: - ... contacts: - ... founded_year: 2006 specialties: - Software Development industry: Software Development domain: twitter.com domain_search_id: 61a73da7-2efc-41a5-a252-a8a8df29925a domain_id: 224475931 linkedin_company_id: 44005587 linkedin_name: twitter is_company_url_active: true domain_ids: - 224475931 - 1758889566 - 368242865 company_keywords: - realtime information - social commerce - online shopping - classifieds - craigslist killers - e-commerce - killers - consumer internet - internet - information technology - edp services - technology - software development - microblogging - social networking - public conversation - user engagement - content sharing - advertising solutions - monetization - community building - digital wallet - ai integration - user safety company_size: 1500 youtube_url: null crunchbase_url: null linkedin_url: http://www.linkedin.com/company/twitter instagram_url: null facebook_url: http://facebook.com/twitterinc twitter_url: https://twitter.com/x github_url: null x_url: null location: United States company_ranking: null company_url: http://twitter.com saved_lists: null company_size_printed: 1,500 - ... '400': $ref: '#/components/responses/general_error' '429': $ref: '#/components/responses/rate_limit_error' '500': $ref: '#/components/responses/server_error' components: schemas: company_name: type: string example: pubrio description: |- Filter search results to include a specific company name. If the value you enter for this parameter does not match with a company's name, the company will not appear in search results, even if it matches other parameters. Partial matches are accepted. companies: type: array items: type: string format: uuid description: >- A list of unique identifiers (domain_search_id) used for company and people search operations. 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. company_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/` company_filters: type: object description: >- Wrapper object for company-level filters. Recommended grouping that visually separates which keys filter the *person* (top-level) from which filter the *company*. Accepts the same keys as the top-level company filters (e.g. `technologies`, `verticals`, `vertical_categories`, `vertical_sub_categories`, `categories`, `keywords`, `founded_dates`, `employees`, `revenues`, `company_locations`, `company_exclude_locations`, `company_places`, `company_exclude_places`, `companies`, `domains`, `company_linkedin_urls`, `is_enable_similarity_search`, `similarity_score`, plus `filter_conditions`). Engine flattens this object to the top level before processing — top-level keys win on conflict. Same shape used by Monitor `company_filters`. See the Filters Overview developer guide for examples. example: company_locations: - US technologies: - 37 - 152 founded_dates: - 2015 - 2023 filter_conditions: - key: technologies operator: and locations: type: array items: type: string example: - US - SG - CN description: >- ISO 3166-1 alpha-2 (cca2) is used for filtering locations. Check out `location` endpoints under the Filters tab for more information. exclude_locations: type: array items: type: string example: - CN - US - RU - CA description: >- ISO 3166-1 alpha-2 (cca2) is used to filter out locations that does not need to be returned. Check out `location` endpoints under the Filters tab for more information. places: type: array items: type: string example: - Tokyo description: >- Place names (city, region) used to filter results. Accepts localized or English place names. exclude_places: type: array items: type: string example: - Tokyo description: >- Place names (city, region) to exclude from results. Accepts localized or English place names. job_exclude_locations: allOf: - $ref: '#/components/schemas/exclude_locations' description: Geographic locations to exclude from job posting results. posted_dates: type: array items: type: string example: - '2025-01-01' - '2025-01-10' description: >- Date range of the posted date. The maximum value is the current day. Day boundaries follow your workspace timezone. people_titles: type: array items: type: string example: - sales manager - marketing manager description: |- Job titles associated with the individuals you aim to locate. The results will also encompass job titles that include similar terminology, even if they do not match exactly. For instance, searching for `software engineer` may yield results for individuals with the title `senior software engineer`. verticals: type: array items: type: integer description: >- A list of `vertical_id` used to search for companies in a specific vertical or industry. To find the ID, call the `vertical` endpoint under the Filters tab. This filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `["AI"]`. vertical_categories: type: array items: type: integer description: >- A list of `vertical_category_id` used to search for companies in a specific vertical category. To find the ID, call the `vertical category` endpoint under the Filters tab. This filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `["Information Technology"]`. vertical_sub_categories: type: array items: type: integer description: >- A list of `vertical_sub_category_id` used to search for companies in a specific vertical sub-category. To find the ID, call the `vertical sub category` endpoint under the Filters tab. This filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `["Software"]`. categories: type: array items: type: integer description: >- A list of `category_id` used to search for specific categories of technology used by companies. To find the ID, call the `category` endpoint under the Filters tab. This filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `["CDN"]`. technologies: type: array items: type: integer description: >- A list of `tag_id` used to search for specific technologies used by companies. To find the ID, call the `technology` endpoint under the Filters tab. This filter supports `is_enable_similarity_search`, once enabled you can enter any free text, e.g. `["Shopify"]`. employees: type: array items: type: array items: type: string example: - - 1 - 10 - - 11 - 20 - - 10001 description: >- The number range of employees working for the company. This enables you to find companies based on headcount. You can add multiple ranges to expand your search results. Check out `company size` endpoints under the Filters tab for more information. revenues: type: array items: type: integer example: - 0 - 100000 description: Minimum and maximum range of company revenue. founded_dates: type: array items: type: integer example: - 2018 - 2024 description: >- Years of company founded range. The maximum value founded is the current year. keywords: type: array items: type: string example: - ecommerce - ai - fintech description: >- A list of keywords to filter companies by relevance, specialties, or descriptions. company_social_media: type: array items: type: string enum: - linkedin - facebook - instagram - tiktok - twitter - x - github - wantedly - rocketpunch example: - tiktok description: >- Companies with a profile on any of: `linkedin`, `facebook`, `instagram`, `tiktok`, `twitter`, `x`, `github`, `wantedly`, `rocketpunch`. Promote to AND with `filter_conditions`. news_categories: type: array items: type: string example: - launches description: >- List of `category slugs` for searching for specific news categories. To find a slug, call the `news categories` endpoint under the Filters tab. published_dates: type: array items: type: string example: - '2025-01-01' - '2025-01-10' description: >- Date range of the published date. The maximum value is the current day. Day boundaries follow your workspace timezone. advertisement_search_terms: type: array items: type: string example: - asus description: Keywords used to search within advertisement content or titles. advertisement_target_locations: allOf: - $ref: '#/components/schemas/target_locations' description: Target geographic locations for advertisements. advertisement_exclude_target_locations: allOf: - $ref: '#/components/schemas/exclude_target_locations' description: Geographic locations to exclude from advertisement targeting. advertisement_start_dates: type: array items: type: string format: date example: - '2025-12-25' - '2025-12-25' description: Start date range for advertisement filtering. advertisement_end_dates: type: array items: type: string format: date example: - '2025-12-25' - '2025-12-25' description: End date range for advertisement filtering. advertisement_active_dates: type: array items: type: string format: date example: - '2026-01-01' - '2026-01-31' description: >- Find advertisements that were running at any point during this date range (overlap-based: includes ads that started before the range and are still running, not just ads that started inside it). advertisement_status: type: array items: type: string enum: - currently_running - active_last_30_min example: - currently_running description: >- `currently_running`: companies with advertising on record. `active_last_30_min`: companies whose advertising changed in the last 30 minutes. advertisement_headlines: type: array items: type: string example: - limited time offer description: Keywords to search for within advertisement headline text. advertisement_platforms: type: array items: type: string enum: - linkedin - facebook - google - tiktok - apple example: - linkedin - facebook description: >- Filter by which ad library the advertisement was sourced from. Lowercase, case-insensitive. `meta` is accepted as an alias for `facebook`. advertisement_publisher_platforms: type: array items: type: string enum: - facebook - instagram - messenger - threads - audience_network 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). advertisement_exclude_publisher_platforms: type: array items: type: string enum: - facebook - instagram - messenger - threads - audience_network example: - audience_network description: Exclude Facebook/Meta ads delivered on these platform surfaces. advertisement_formats: type: array items: type: string enum: - image - video - text - carousel - dynamic_product - document - message - event - article - spotlight - follow - job - engagement example: - image - video description: >- Find companies with at least one advertisement in any of these creative formats. advertisement_active_ads: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null 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". advertisement_running_ads: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null 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_total_ads: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 10 - null description: >- Minimum and maximum count of the company's total advertisements ever recorded, across all countries. advertisement_platform_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 2 - null description: >- Minimum and maximum number of distinct ad platforms (linkedin, facebook, google, tiktok, apple) the company is actively advertising on. advertisement_format_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 2 - null description: >- Minimum and maximum number of distinct advertisement creative formats the company is actively running. advertisement_impressions_estimate: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1000 - null description: >- Minimum and maximum estimated advertisement impressions, summed across all countries. Only advertisements with a reported impression range are counted. advertisement_country_activity: type: object properties: country: type: string example: US description: ISO 3166-1 alpha-2 country code to scope this filter to. Required. rank: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - null - 500 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. percentile: type: array items: type: number nullable: true minItems: 2 maxItems: 2 example: - 90 - null 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. volume_score: type: array items: type: number nullable: true minItems: 2 maxItems: 2 example: - 0.5 - null description: >- The underlying 0-1 advertising volume score that `rank` and `percentile` are both computed from. active_ads: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: Minimum and maximum active advertisements, scoped to this country. running_ads: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: >- Minimum and maximum running advertisements, scoped to this country. Currently populated for LinkedIn ads only. total_ads: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 10 - null description: Minimum and maximum total advertisements, scoped to this country. impressions: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1000 - null description: Minimum and maximum estimated impressions, scoped to this country. first_seen: type: array items: type: string nullable: true format: date minItems: 2 maxItems: 2 example: - '2026-07-01' - null 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. last_seen: type: array items: type: string nullable: true format: date minItems: 2 maxItems: 2 example: - '2026-07-01' - null 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. required: - country example: country: US rank: - null - 500 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. company_sort_by: type: string enum: - relevance - name - number_of_employees - founded_year - advertisement_country_rank example: advertisement_country_rank description: >- Result ordering. Omit for the default relevance order. `advertisement_country_rank` orders by the company's advertising rank inside the country named in `advertisement_country_activity` (rank 1 = biggest advertiser in that market) and is ignored unless that filter is present. Pair with `is_ascending_order: false` to list the smallest advertisers first. Not yet available: `name` (either direction) and `relevance` with `is_ascending_order: false` — those requests time out. Use the default relevance order, `number_of_employees` or `founded_year` instead. company_filter_conditions: type: array items: type: object properties: key: type: string enum: - keywords - verticals - vertical_categories - vertical_sub_categories - technologies - categories - advertisement_target_locations - advertisement_exclude_target_locations - advertisement_search_terms - places - exclude_places - job_exclude_locations example: keywords description: The filter key specifying which property to apply the operator to. operator: type: string enum: - or - and example: or description: >- The logical operator to apply. Use 'or' to match any of the specified values, or 'and' to require all specified values. description: >- Advanced filtering options for company searches. Specify conditions combining keys and logical operators to refine search results. is_enable_similarity_search: type: boolean description: >- When enabled, the filters listed above that support similarity searches can be filled with free text for specific IDs. similarity_score: type: number format: float example: 0.7 description: >- It is used in conjunction with `is_enable_similarity_search`. This number is used to analyze whether a specific slug (e.g. vertical industry, technology) is similar to the user input, and the higher the number, the more stringent it is. exclude_fields: type: array items: type: string example: - emails - phones - contacts description: List of fields to exclude from the response payload. is_parameter_metadata_available: type: boolean description: Indicates whether parameter metadata is available for the request. is_profile_metadata_available: type: boolean description: Indicates whether profile metadata is available for the request. per_page: type: integer example: 25 default: 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. page: type: integer example: 1 default: 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**. cloud_footprint_providers: type: array items: type: string example: - AWS - Cloudflare description: >- Companies that use any of these providers anywhere. The unprefixed `providers` narrows the rows returned; this narrows the companies. exclude_providers: type: array items: type: string example: - AWS - Cloudflare - Hetzner description: >- Remove footprint rows matching these cloud or hosting providers. Scoped to this footprint row — one provider in one country. cloud_footprint_target_locations: type: array items: type: string example: - DE - SG description: Companies present in any of these countries anywhere in their footprint. cloud_footprint_exclude_target_locations: type: array items: type: string example: - DE - US - SG description: >- Remove footprint rows matching these country codes the infrastructure sits in. cloud_regions: type: array items: type: string example: - us-east-1 - eu-central-1 description: >- Restrict results to footprint rows matching these cloud regions. Scoped to this footprint row — one provider in one country. exclude_cloud_regions: type: array items: type: string example: - us-east-1 - eu-central-1 description: >- Remove footprint rows matching these cloud regions. Scoped to this footprint row — one provider in one country. cities: type: array items: type: string example: - Ashburn - Frankfurt description: >- Restrict results to footprint rows matching these cities. Scoped to this footprint row — one provider in one country. exclude_cities: type: array items: type: string example: - Ashburn - Frankfurt description: >- Remove footprint rows matching these cities. Scoped to this footprint row — one provider in one country. first_seen_dates: type: array items: type: string nullable: true minItems: 2 maxItems: 2 example: - '2026-01-01' - null description: >- Two ISO 8601 dates (YYYY-MM-DD) bounding when the footprint was first seen. Scoped to this footprint row — one provider in one country. last_seen_dates: type: array items: type: string nullable: true minItems: 2 maxItems: 2 example: - '2026-01-01' - null description: >- Two ISO 8601 dates (YYYY-MM-DD) bounding when the footprint was last seen. Scoped to this footprint row — one provider in one country. is_cross_border_only: type: boolean example: true description: >- When true, return only footprint rows outside the company's home market. Rows whose company has no known headquarters are excluded. cloud_footprint_host_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: >- Minimum and maximum hosts. Use `null` for an open-ended bound. Counted for the whole company, across every provider and country. cloud_footprint_server_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: >- Minimum and maximum servers (distinct IP addresses). Use `null` for an open-ended bound. Counted for the whole company, across every provider and country. cloud_footprint_shared_server_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: >- Minimum and maximum servers shared with other companies. Use `null` for an open-ended bound. Counted for the whole company, across every provider and country. cloud_footprint_provider_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: >- Minimum and maximum distinct providers used by the company. Use `null` for an open-ended bound. Counted for the whole company, across every provider and country. cloud_footprint_country_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: >- Minimum and maximum countries the company hosts in. Use `null` for an open-ended bound. Counted for the whole company, across every provider and country. cloud_footprint_cross_border_country_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: >- Minimum and maximum countries outside the company's home market. Use `null` for an open-ended bound. Counted for the whole company, across every provider and country. cloud_footprint_region_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: >- Minimum and maximum cloud regions. Use `null` for an open-ended bound. Counted for the whole company, across every provider and country. cloud_footprint_city_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 1 - null description: >- Minimum and maximum cities. Use `null` for an open-ended bound. Counted for the whole company, across every provider and country. cloud_footprint_primary_provider: type: array items: type: string example: - AWS description: Companies whose single largest provider is one of these. cloud_footprint_country_activity: type: object required: - country properties: country: type: string example: DE description: ISO 3166-1 alpha-2 country code. host_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 100 - null server_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 100 - null shared_server_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 100 - null region_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 100 - null city_count: type: array items: type: integer nullable: true minItems: 2 maxItems: 2 example: - 100 - null first_seen: type: array items: type: string nullable: true minItems: 2 maxItems: 2 example: - '2026-07-01' - null last_seen: type: array items: type: string nullable: true minItems: 2 maxItems: 2 example: - '2026-07-01' - null description: >- Bounds scoped to one country: `{"country":"DE","host_count":[100,null]}` finds companies running 100+ hosts in Germany specifically. The bare `cloud_footprint_host_count` is the company total across all countries, so the two cannot express this together. `country` alone is rejected. data: type: object nullable: true description: Response info depends on specific endpoint. 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. 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. responses: general_error: description: >- Bad request. The request was malformed or contained invalid parameters. Check the error code and message for details. content: application/json: schema: required: - code - message - details type: object properties: code: example: 40001 type: integer message: example: >- Errors and codes will vary depending on the scenario, please see the documentation for information. type: string details: type: object rate_limit_error: description: >- Rate limit exceeded. Too many requests were made in a given time period. Retry after the rate limit window resets. content: application/json: schema: required: - error type: object properties: error: example: Request rate limit exceeded. Please wait and try again later. type: string server_error: description: >- Internal server error. An unexpected error occurred on the server. Contact support if the error persists. content: application/json: schema: required: - error type: object properties: error: example: An unexpected error occurred on the server. type: string securitySchemes: pubrio_api_key: type: apiKey name: pubrio-api-key description: >- 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](https://dashboard.pubrio.com/#/settings/) section. in: header ````