Skip to main content
POST
Expansion Search

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
​
froms
string[]
required

Origin markets (ISO 3166-1 alpha-2). Where a company is expanding FROM — its home / HQ countries. Use alone to find companies growing out of these markets; combine with tos for a specific from→to corridor.

Example:
​
tos
string[]

Target markets (ISO 3166-1 alpha-2). Where a company is expanding TO. Use alone to find every company entering these markets; combine with froms for a specific from→to corridor.

Example:
​
exclude_froms
string[]

Origin markets to exclude (ISO 3166-1 alpha-2).

Example:
​
exclude_tos
string[]

Target markets to exclude (ISO 3166-1 alpha-2).

Example:
​
stages
enum<string>[]

Values are case-sensitive and are not validated. An unrecognised value is silently discarded rather than rejected: on stages, freshness, scopes and momentum the whole filter is dropped and you get unfiltered results, while on signal_types and signal_strengths the filter is applied and matches nothing. Either way the response looks normal. Resolve valid slugs from Expansion Reference and compare data.pagination.total_entries against an unfiltered call if a result set looks wrong.

Available options:
exploring,
committing,
expanding,
scaling
Example:
​
momentum
enum<string>[]

Trajectory of the company's movement in the market. advancing is gaining ground, steady is holding, pulling_back covers retreat and contraction.

Do not use the values from directions in Expansion Reference here. Those (advancing, steady, retreating, new) are the response values you get back on stage.direction; only the three listed above are accepted as a filter. Sending retreating or new silently disables the filter and returns unfiltered results.

Available options:
advancing,
steady,
pulling_back
Example:
​
freshness
enum<string>[]

Values are case-sensitive and are not validated. An unrecognised value is silently discarded rather than rejected: on stages, freshness, scopes and momentum the whole filter is dropped and you get unfiltered results, while on signal_types and signal_strengths the filter is applied and matches nothing. Either way the response looks normal. Resolve valid slugs from Expansion Reference and compare data.pagination.total_entries against an unfiltered call if a result set looks wrong.

Available options:
fresh,
cooling,
stale,
cold
Example:
​
scopes
enum<string>[]

Filter by market-entry scope.

Available options:
entering_new_market,
expanding_within_presence,
established_only
Example:
​
ahead_of_pace
boolean

Limit to pairs moving faster than the typical pace for that market.

Example:

false

​
signal_types
enum<string>[]

Values are case-sensitive and are not validated. An unrecognised value is silently discarded rather than rejected: on stages, freshness, scopes and momentum the whole filter is dropped and you get unfiltered results, while on signal_types and signal_strengths the filter is applied and matches nothing. Either way the response looks normal. Resolve valid slugs from Expansion Reference and compare data.pagination.total_entries against an unfiltered call if a result set looks wrong.

Available options:
AD,
AUDIENCE,
DNS,
ENTITY,
EVENT,
EVENT_PLUS,
EXEC,
HIRE,
INFRA,
IP,
NEWS,
OFFICE,
PARTNER,
PRODUCT,
REG,
SCALE,
TECH
Example:
​
signal_strengths
enum<string>[]

Values are case-sensitive and are not validated. An unrecognised value is silently discarded rather than rejected: on stages, freshness, scopes and momentum the whole filter is dropped and you get unfiltered results, while on signal_types and signal_strengths the filter is applied and matches nothing. Either way the response looks normal. Resolve valid slugs from Expansion Reference and compare data.pagination.total_entries against an unfiltered call if a result set looks wrong.

Available options:
low,
medium,
high,
very_high
Example:
​
min_signal_count
integer

Minimum number of expansion signals a company must have in the window — "very active / heavy footprint".

Example:

3

​
only_contraction
boolean

When true, return only contraction-flagged expansions (companies scaling back).

Example:

false

​
min_markets
integer

Minimum number of new markets a company must have entered in the window.

Example:

3

​
home_country_code
string[]

Filter by company home country (ISO 3166-1 alpha-2). Intersects with froms when both are supplied.

Example:
​
industries
string[]

Filter by industry name (free-text match).

Example:
​
exclude_industries
string[]

Industries to exclude (free-text match).

Example:
​
verticals
integer[]

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
integer[]

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
integer[]

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"].

​
technologies
integer[]

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"].

A product name the technology list knows matches that product and its own products ("Salesforce" also matches Salesforce Desk and Salesforce Service Cloud), never look-alikes; other text matches by similarity.

​
employees
string[][]

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.

Example:
​
revenues
integer[]

Minimum and maximum range of company revenue.

Example:
​
founded_dates
integer[]

Years of company founded range. The maximum value founded is the current year.

Example:
​
keywords
string[]

A list of keywords to filter companies by relevance, specialties, or descriptions.

Example:
​
companies
string[]

Scope to specific companies by any mix of domain_search_id, company domain, or a company social media profile URL. Domains and URLs resolve to their best-ranked company.

Example:
​
job_locations
string[]

ISO 3166-1 alpha-2 (cca2) is used for filtering locations. Check out location endpoints under the Filters tab for more information.

Example:
​
job_exclude_locations
string[]

Geographic locations to exclude from job posting results.

Example:
​
job_posted_dates
string[]

Date range of the posted date. The maximum value is the current day. Day boundaries follow your workspace timezone.

Example:
​
job_titles
string[]

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.

Example:
​
advertisement_target_locations
string[]

Target geographic locations for advertisements.

Example:
​
advertisement_exclude_target_locations
string[]

Geographic locations to exclude from advertisement targeting.

Example:
​
advertisement_search_terms
string[]

Keywords used to search within advertisement content or titles.

Example:
​
advertisement_start_dates
string<date>[]

Start date range for advertisement filtering.

Example:
​
advertisement_end_dates
string<date>[]

End date range for advertisement filtering.

Example:
​
news_categories
string[]

List of category slugs for searching for specific news categories. To find a slug, call the news categories endpoint under the Filters tab.

Example:
​
news_published_dates
string[]

Date range of the published date. The maximum value is the current day. Day boundaries follow your workspace timezone.

Example:
​
transitioned_dates
string<date>[]

ISO date range for the timeline window. Defaults to the last 90 days. A natural-language query may also set this from calendar phrases ("this year", "last year", "Q2 2026").

Example:
​
window_days
integer

Optional. Size of the rolling window in days. Used when an explicit transitioned_dates range is not supplied; if both are omitted, a default window is used.

Example:

90

​
query
string

Natural-language query that Pubrio interprets into expansion + company filters.

Example:

"fintech companies expanding into the UK"

​
is_explain_match
boolean

Include AI-generated explanations of why each company matches the search, grounded in the company's real signals. Best paired with a natural-language query. The number of signals cited and the batch size both scale with per_page; high-volume sources (job postings, ad campaigns) are summarized as a window-scoped count (e.g. "12 job postings") rather than listed individually.

Example:

true

​
sort_by
enum<string>

Result ordering. Omit for the default relevance order: corroborated pairs first (2+ distinct signal types), then repeated-evidence pairs (3+ signals), then the rest — most recently transitioned first within each tier. recent — pure recency (most recently transitioned first). expansion_score — highest expansion score first. signal_count — most signals in the pair first. company_ranking — Pubrio's overall company ranking (lower is more prominent), ascending.

Available options:
recent,
expansion_score,
signal_count,
company_ranking
Example:

"expansion_score"

​
is_include_metadata
boolean

Return the full detail payload. API-key traffic is lean by default: the model block, the confidence figures (stage.confidence on Company Expansion Detail, confidence_score on other_markets[] and on Rankings markers[]) and the established_min / share_of_detected / has_known_office fields are all omitted unless this is true.

Example:

true

​
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

​
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

​
is_enable_similarity_search
boolean

Enable free-text matching for verticals, vertical_categories, vertical_sub_categories and technologies. Without it, free-text values in those filters match nothing.

Example:

true

​
filter_conditions
object[]

Advanced filtering options for company searches. Specify conditions combining keys and logical operators to refine search results.

Response

Paginated list of companies expanding in the market(s). filters echoes the applied (or natural-language-interpreted) criteria; each company includes a match_summary when is_explain_match is true.

​
metadata
object

Search metadata: the filters actually applied, plus the market rollup (aggregate, geo scope, top origins/destinations/industries, timeline). API-key responses include the rollup only when is_include_metadata is true.

​
data
object

Result container (standard search envelope): the company list plus pagination.

Last modified on August 28, 2026