Using the Expansion API

This quickstart gets you from zero to reading live expansion signals in a few calls. It assumes you already have a Pubrio API key — see Authentication to create one.

Prerequisites

A Pubrio API key (see Authentication).
A company’s domain_search_id. You can get one from the Company Search endpoint.

All Expansion endpoints are POST and accept a JSON body. Include your credentials on every request as described in Authentication.

Step 1 — Look up a company’s expansion

Start with a single company and list every market it is expanding into.

POST /expansions/companies/lookup
{ "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "is_all_markets": true }

{
  "metadata": { "domain_search_id": "550e8400-e29b-41d4-a716-446655440002", "home_country_code": "US" },
  "data": { "market_count": 2, "dominant_stage_slug": "expanding", "total_signal_count": 194 },
  "markets_summary": [
    { "country_code": "GB", "stage_slug": "expanding", "is_home_market": false, "signal_count": 140, "distinct_type_count": 6, "latest_signal_at": "2026-07-08T02:42:23.544Z", "rank_now": 1 },
    { "country_code": "DE", "stage_slug": "committing", "is_home_market": false, "signal_count": 54, "distinct_type_count": 3, "latest_signal_at": "2026-06-20T00:00:00.000Z", "rank_now": 2 }
  ]
}

Step 2 — Read the result

Each entry in markets_summary describes one market the company is active in:

stage_slug — how far the company has progressed there (exploring → scaling).
signal_count / distinct_type_count — how much evidence backs the market, across how many signal types.
latest_signal_at — recency of the newest signal.
signal_velocity_30d / signal_velocity_90d — how fast activity is picking up.
rank_now — the market’s current rank for this company (1 = strongest).
is_home_market — whether this is the company’s HQ country.

To surface the freshest movers or filter by trajectory, use the discovery endpoints (freshness, momentum) shown next.

Step 3 — Explore a whole market

To work market-first instead of company-first, use Expansion Market Detail. It is paginated with the standard page / per_page parameters. Geography is a directed from → to relationship, expressed with two lists: froms (origin / HQ markets) and tos (target markets). Pick the pattern that matches your question:

POST /expansions/search
{
  "tos": ["GB"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}

POST /expansions/search
{
  "froms": ["CN"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}

POST /expansions/search
{
  "froms": ["CN"],
  "tos": ["GB"],
  "page": 1,
  "per_page": 25
}

Read metadata.pagination to page through results:

{
  "metadata": {
    "filters": { "tos": ["GB"], "freshness": ["fresh", "cooling"] }
  },
  "data": {
    "pagination": { "page": 1, "per_page": 25, "total_entries": 64, "total_pages": 3 },
    "companies": [ /* ... */ ]
  }
}

Request the next page by incrementing page. per_page is capped by your plan — explicitly requesting more than your cap returns an error rather than silently truncating. Two defaults worth knowing:

Ordering — results come back in relevance order (companies corroborated by multiple signal types first, then most recent). Pass sort_by: "recent" for pure recency, or expansion_score / signal_count / company_ranking.
Lean responses — API-key responses omit the market rollup (metadata.aggregate, top origins/destinations, timeline) and model detail by default. Pass is_include_metadata: true when you want them.

Step 4 — Drill into the evidence

When you want the individual signals behind a company’s move, call Company Signal Events.

POST /expansions/companies/pulse_events
{
  "domain_search_id": "550e8400-e29b-41d4-a716-446655440002",
  "signal_types": ["HIRE", "EXEC", "NEWS"],
  "window_days": 90,
  "page": 1
}

This endpoint returns total_entries and total_pages — request pages 1 through total_pages (i.e. keep going while page < total_pages).

Filtering reference

Most expansion endpoints accept these filters. Their valid values are listed in How Expansion Signals Work:

Filter	Purpose
`stages`	Limit to one or more expansion stages.
`freshness`	Limit by evidence recency.
`momentum`	Limit by trajectory (`accelerating`/`advancing`/`steady`/`pulling_back`).
`scopes`	Limit by market-entry scope.
`signal_types`	Limit to specific signal types.
`froms`	Origin / HQ markets (expanding from).
`tos`	Target markets (expanding into).
`companies`	Scope to specific companies by `domain_search_id`, domain, or LinkedIn URL.

The companies filter accepts any mix of identifier types — no need to resolve to IDs first:

POST /expansions/search
{ "companies": ["stripe.com", "airbnb.com"] }

POST /expansions/search
{ "companies": ["https://www.linkedin.com/company/stripe"] }

POST /expansions/search
{ "companies": ["550e8400-e29b-41d4-a716-446655440002"] }

Don’t confuse flow with trajectory. Flow (the direction of the move between markets) is set by froms / tos — there is no direction request filter. Trajectory (how the move is progressing) is the momentum filter, and it surfaces in responses as the direction field.

Knowledge Base

Guides

Concepts

Case Studies

Prerequisites

Step 1 — Look up a company’s expansion

Step 2 — Read the result

Step 3 — Explore a whole market

Step 4 — Drill into the evidence

Filtering reference

Next steps

Worked Example

Expansion endpoints

​Prerequisites

​Step 1 — Look up a company’s expansion

​Step 2 — Read the result

​Step 3 — Explore a whole market

​Step 4 — Drill into the evidence

​Filtering reference

​Next steps

Worked Example

Expansion endpoints

Prerequisites

Step 1 — Look up a company’s expansion

Step 2 — Read the result

Step 3 — Explore a whole market

Step 4 — Drill into the evidence

Filtering reference

Next steps