> ## 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.

# Using the Expansion API

> Authenticate, make your first Expansion API calls, paginate results, and read expansion scores.

<Info>
  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](/en/api-reference/authentication) to create one.
</Info>

## Prerequisites

* A Pubrio API key (see [Authentication](/en/api-reference/authentication)).
* A company's `domain_search_id`. You can get one from the [Company Search](/en/api-reference/endpoint/companies/search) endpoint.

All Expansion endpoints are `POST` and accept a JSON body. Include your credentials on every request as described in [Authentication](/en/api-reference/authentication).

## Step 1 — Look up a company's expansion

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

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

```json theme={null}
{
  "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](/en/api-reference/endpoint/expansions/market_lookup). 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:

<CodeGroup>
  ```bash Inbound (into GB) theme={null}
  POST /expansions/lookup
  {
    "tos": ["GB"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

  ```bash Outbound (from CN) theme={null}
  POST /expansions/lookup
  {
    "froms": ["CN"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

  ```bash Corridor (CN → GB) theme={null}
  POST /expansions/lookup
  {
    "froms": ["CN"],
    "tos": ["GB"],
    "page": 1,
    "per_page": 25
  }
  ```
</CodeGroup>

Read `metadata.pagination` to page through results:

```json theme={null}
{
  "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](/en/api-reference/endpoint/expansions/company_pulse_events).

```bash theme={null}
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](/en/knowledge-base/concepts/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:

<CodeGroup>
  ```bash By domain theme={null}
  POST /expansions/lookup
  { "companies": ["stripe.com", "airbnb.com"] }
  ```

  ```bash By LinkedIn URL theme={null}
  POST /expansions/lookup
  { "companies": ["https://www.linkedin.com/company/stripe"] }
  ```

  ```bash By domain_search_id theme={null}
  POST /expansions/lookup
  { "companies": ["550e8400-e29b-41d4-a716-446655440002"] }
  ```
</CodeGroup>

<Warning>
  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.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Worked Example" href="/en/knowledge-base/concepts/expansion-signals-example">
    The full market-to-signal walkthrough.
  </Card>

  <Card title="Expansion endpoints" href="/en/api-reference/endpoint/expansions/dashboard">
    Browse every Expansion API endpoint.
  </Card>
</CardGroup>