> ## 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.
# Expansion Field Reference
> A field-by-field dictionary for the Expansion API — every request filter and response field, its type, allowed values, and meaning.
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](/en/knowledge-base/concepts/how-expansion-signals-work) and the value catalog in [How Expansion Signals Work](/en/knowledge-base/concepts/how-expansion-signals-work). For an always-current list of allowed values, call the [Expansion Taxonomy](/en/api-reference/endpoint/expansions/types) 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`. |
| `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.