Expansion Field Reference

This is the field dictionary for the Expansion API: what each request filter does and what each response field means. For the why behind the model, see How Expansion Signals Work and the value catalog in How Expansion Signals Work. For an always-current list of allowed values, call the Expansion Taxonomy endpoint.

Core dimensions

Every expansion is described along a few independent axes. Don’t confuse them:

Field	What it captures	Example values
`stage`	How far a company has progressed in a market	`exploring`, `committing`, `expanding`, `scaling`, `established`
`momentum`	The trajectory of the move right now	`accelerating`, `advancing`, `steady`, `pulling_back`
flow	The direction of the move between markets, expressed with `froms` / `tos`	outbound (`froms`), inbound (`tos`), corridor (`froms`→`tos`)
`freshness`	How recent the evidence is	`fresh`, `cooling`, `stale`, `cold`
`scope`	Whether it’s a new market or growth within an existing presence	`entering_new_market`, `expanding_within_presence`, `established_only`
`expansion_score`	A sortable 0–1 rank of how significant the expansion is	`0.72`

The stage slugs are exploring, committing, expanding, scaling, and established — each matching its display name: Exploring, Committing, Expanding, Scaling, and Established.

Flow (the direction of the move) and momentum (the trajectory) are different things. Filtering by “companies advancing” is momentum: ["advancing"]; filtering by “companies expanding into the US” is tos: ["US"]. There is no separate direction request field — flow is set entirely by froms / tos.

Request filters

Markets (`froms` / `tos`)

Geography is a directed relationship: companies expand from an origin to a target. Two lists express every case — no separate direction flag.

Param	Type	Meaning
`froms`	string[] (ISO alpha-2)	Origin markets — where the company is expanding FROM (its home / HQ).
`tos`	string[] (ISO alpha-2)	Target markets — where the company is expanding TO.
`exclude_froms`	string[] (ISO alpha-2)	Origin markets to exclude.
`exclude_tos`	string[] (ISO alpha-2)	Target markets to exclude.

You send	You get
`tos: ["US"]`	Everyone expanding into the US (inbound).
`froms: ["CN"]`	Chinese companies expanding anywhere (outbound).
`froms: ["CN"]`, `tos: ["US"]`	The CN → US corridor only.
neither	All expansions, worldwide.

Expansion signal filters

Param	Type	Meaning
`stages`	string[]	Filter to one or more expansion stages.
`momentum`	string[]	Filter by trajectory (`accelerating`/`advancing`/`steady`/`pulling_back`).
`freshness`	string[]	Filter by evidence recency (`fresh`/`cooling`/`stale`/`cold`).
`scopes`	string[]	Filter by `entering_new_market` / `expanding_within_presence` / `established_only`.
`signal_types`	string[]	Restrict to specific signal types (`HIRE`, `OFFICE`, `AD`, `NEWS`, `DNS`, …).
`signal_strengths`	string[]	Filter by evidence-confidence bucket: `low`, `medium`, or `high`. (Distinct from the per-signal `signal_strength_slug`, which ranges up to `very_high`.)
`min_signal_count`	integer	Minimum number of expansion signals — surfaces heavy-footprint movers.
`ahead_of_pace`	boolean	Only companies moving faster than that market’s typical pace.
`only_contraction`	boolean	Only at-risk / shrinking markets.
`min_markets`	integer	Minimum distinct new markets a company has entered in the window.

Firmographics

Param	Type	Meaning
`verticals`, `technologies`	string[]	Company industry / tech-stack filters.
`employees`	number[][]	Head-count ranges, e.g. `[[50, 200]]`.
`founded_dates`	number[]	Founded-year range `[from, to]`.
`revenues`	number[]	Revenue range in USD `[from, to]`.
`keywords`	string[]	Free-text theme scoping.
`companies`	string[]	Scope to specific companies by any mix of `domain_search_id`, domain, or LinkedIn URL (domains / URLs resolve to their best-ranked company).

Time window & search

Param	Type	Meaning
`transitioned_dates`	string[]	Signal/transition window as an ISO `[from, to]` range.
`window_days`	integer	Rolling window in days, used when `transitioned_dates` is not supplied.
`query`	string	Natural-language search — Pubrio interprets it into filters (echoed back in `filters`).
`is_explain_match`	boolean	Add an AI `match_summary` per company, grounded in its real signals. Cited signal count and batch size scale with `per_page`; high-volume sources (job postings, ad campaigns) are summarized as a count rather than listed individually.
`sort_by`	string	Result ordering: `recent`, `expansion_score`, `signal_count`, or `company_ranking`. Omit for the default relevance order — corroborated pairs (2+ distinct signal types) first, then repeated-evidence pairs (3+ signals), most recent first within each tier. Use `recent` for pure recency.

Response fields

Per-company / per-market `stage`

Field	Meaning
`stage.slug`	The current stage (`exploring` … `scaling`).
`stage.expansion_score`	Sortable 0–1 significance rank.
`stage.scope`	New-market vs within-presence.
`stage.direction`	Trajectory of the stage: `advancing`, `steady`, `retreating`, or `new`. This is the response-side view of the same trajectory axis you filter on with the `momentum` request param — the two use different value sets, so map accordingly.
`stage.freshness`	Recency bucket of the latest evidence.
`stage.signal_count`	Number of active expansion signals in this market.
`stage.first_signal_at` / `latest_signal_at` / `last_transition_at`	Key timestamps.

Signals, presence & explanation

Field	Meaning
`signals[]`	The underlying evidence: `signal_type`, `signal_subtype`, `signal_strength`, `polarity`, `event_date`, `source_type`, `display_label`, `evidence_url`.
`presence[]`	Known in-market footprint (offices/entities): `presence_type`, `presence_strength`, `address`, `known_since`.
`timeline[]`	Stage-transition history: `stage_slug`, `transitioned_at`, `transition_kind`.
`other_markets[]`	The company’s other active markets, each with its stage + counts.
`match_summary`	(when `is_explain_match: true`) `{ text, citations }` — an AI “why it matches”, cited to that company’s real signals. Each citation carries a `count` field: `null` for a real individual signal, or an integer when the citation is a window-scoped volume count (job postings, ad campaigns) rather than a single event.

expansion_score is a sortable rank (comparable across companies). It is distinct from the model confidence, which API-key responses include only when is_include_metadata: true is set.

Knowledge Base

Guides

Concepts

Case Studies

Core dimensions

Request filters

Markets (`froms` / `tos`)

Expansion signal filters

Firmographics

Time window & search

Response fields

Per-company / per-market `stage`

Signals, presence & explanation

​Core dimensions

​Request filters

​Markets (froms / tos)

​Expansion signal filters

​Firmographics

​Time window & search

​Response fields

​Per-company / per-market stage

​Signals, presence & explanation

Core dimensions

Request filters

Markets (`froms` / `tos`)

Expansion signal filters

Firmographics

Time window & search

Response fields

Per-company / per-market `stage`

Signals, presence & explanation