Skip to main content
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

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/lookup
{
  "tos": ["GB"],
  "freshness": ["fresh", "cooling"],
  "page": 1,
  "per_page": 25
}

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

POST /expansions/lookup
{
  "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.

​
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:
FilterPurpose
stagesLimit to one or more expansion stages.
freshnessLimit by evidence recency.
momentumLimit by trajectory (accelerating/advancing/steady/pulling_back).
scopesLimit by market-entry scope.
signal_typesLimit to specific signal types.
fromsOrigin / HQ markets (expanding from).
tosTarget markets (expanding into).
companiesScope 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/lookup
{ "companies": ["stripe.com", "airbnb.com"] }

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

POST /expansions/lookup
{ "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.

​
Next steps

Worked Example

The full market-to-signal walkthrough.

Expansion endpoints

Browse every Expansion API endpoint.