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. |
signal_types | string[] | Restrict to specific signal types (HIRE, OFFICE, AD, NEWS, …). |
signal_strengths | string[] | Filter by evidence intensity bucket (e.g. high, 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: expansion_score, signal_count, or company_ranking. Omit for the default (most recently transitioned first). |
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 any internal model confidence, which the public API does not return.
