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

# Choosing an Expansion Endpoint

> A task-to-endpoint guide for the Expansion API — which endpoint to call for discovery, company detail, the signal feed, comparison, maps, and reference values.

The Expansion API is a small set of endpoints, each answering a different question about how companies grow into new markets. This guide maps **what you want to do** to **which endpoint to call**, so you never have to guess.

<Info>
  New to the concepts (stages, signals, momentum, freshness)? Start with [What Are Expansion Signals?](/en/knowledge-base/concepts/expansion-signals) — this guide assumes you know them and focuses on endpoint selection.
</Info>

## Pick by task

| You want to…                                                                                                                                        | Call                                                                                         |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Find companies** expanding into a market (by filters or a natural-language query)                                                                 | [Expansion Search](/en/api-reference/endpoint/expansions/market_lookup)                      |
| See **market-level KPIs and flows** (counts per stage, top corridors)                                                                               | [Expansion Overview](/en/api-reference/endpoint/expansions/dashboard)                        |
| Get **one company's status in a market** — stage, presence, history, and the signals behind it                                                      | [Company Expansion Detail](/en/api-reference/endpoint/expansions/company_lookup)             |
| Get the **enriched, time-windowed feed** of a company's signal events                                                                               | [Company Signal Events](/en/api-reference/endpoint/expansions/company_pulse_events)          |
| **Compare** several companies' expansion side by side, seeded from a target company                                                                 | [Compare Company Expansions](/en/api-reference/endpoint/expansions/company_compare)          |
| Get **ready-to-render comparison metrics** (markets, momentum, expansion score) for a company set you already have — by domain, LinkedIn URL, or id | [Batch Company Expansion Summaries](/en/api-reference/endpoint/expansions/company_summaries) |
| Plot **ranked company/market points** on a map or heatmap                                                                                           | [Expansion Rankings](/en/api-reference/endpoint/expansions/company_markers)                  |
| Resolve **filter and enum values** (stages, signal types, freshness…)                                                                               | [Expansion Reference](/en/api-reference/endpoint/expansions/types)                           |

## The endpoints at a glance

<CardGroup cols={2}>
  <Card title="Expansion Search" icon="magnifying-glass" href="/en/api-reference/endpoint/expansions/market_lookup">
    The discovery endpoint. Filter companies by expansion stage, freshness, market, and the full company firmographic suite — or pass a natural-language `query`. Paginated company list.
  </Card>

  <Card title="Expansion Overview" icon="chart-simple" href="/en/api-reference/endpoint/expansions/dashboard">
    Market-level aggregates: per-stage counts, top cross-border flows, watched-company activity. No pagination — a dashboard snapshot.
  </Card>

  <Card title="Company Expansion Detail" icon="building-magnifying-glass" href="/en/api-reference/endpoint/expansions/company_lookup">
    One company in one market: current stage, score, presence, transition history, and the supporting signals. The per-market snapshot.
  </Card>

  <Card title="Company Signal Events" icon="timeline" href="/en/api-reference/endpoint/expansions/company_pulse_events">
    The enriched, paginated feed of a company's signal events across signal types and a date window. The activity drill-down.
  </Card>

  <Card title="Compare Company Expansions" icon="scale-balanced" href="/en/api-reference/endpoint/expansions/company_compare">
    Several companies side by side in one call, with weekly signal series and optional peer seeding. Built for comparison grids.
  </Card>

  <Card title="Batch Company Expansion Summaries" icon="table" href="/en/api-reference/endpoint/expansions/company_summaries">
    Any mix of domain\_search\_id, domain, or LinkedIn URL, resolved and returned with the same data as Compare plus a computed summary block — no target company, no peer seeding.
  </Card>

  <Card title="Expansion Rankings" icon="map-location-dot" href="/en/api-reference/endpoint/expansions/company_markers">
    A lightweight, score-ranked list of company/market pairs — minimal fields, no pagination — for fast map and heatmap rendering.
  </Card>
</CardGroup>

## "Detail" vs "Signal Events" — which one?

This is the most common point of confusion, because **both involve signals**. The difference is *snapshot vs feed*:

|              | Company Expansion Detail                                                                  | Company Signal Events                                                                                           |
| ------------ | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Scope**    | one company × **one market**                                                              | one company, across **all its foreign markets**                                                                 |
| **Markets**  | a **single market** via `country_code`, or the whole company at once via `is_all_markets` | **all foreign markets** by default (home market excluded); narrow to specific ones with `country_codes` (array) |
| **Returns**  | stage, score, presence, history **+ supporting signals**                                  | **enriched signal events** (evidence URLs, hiring rosters, labels)                                              |
| **Time**     | current standing                                                                          | a **date window** you choose (`window_days` — defaults to 90 — or `transitioned_dates`)                         |
| **Shape**    | a structured snapshot object                                                              | a paginated event feed ("load more")                                                                            |
| **Use when** | "What's this company's status in **one** market, and why?"                                | "Show me the full stream across **every** market driving this company's expansion"                              |

<Tip>
  **Most integrations only need Company Expansion Detail** — it already returns the signals behind a company's stage in a market. Reach for **Company Signal Events** when you specifically want the rich, filterable, time-windowed event stream (e.g. building an activity timeline UI).
</Tip>

## "Compare" vs "Summaries" — which one?

Both return the same per-company expansion data side by side. The difference is *identifiers and framing*:

|                     | Compare Company Expansions                                                     | Batch Company Expansion Summaries                                                                        |
| ------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| **Input**           | `domain_search_id` only                                                        | any mix of `domain_search_id`, `domain`, or `linkedin_url`                                               |
| **Peer seeding**    | optional, via `seed_target`                                                    | none — every company is independent                                                                      |
| **Computed rollup** | none (compute markets/momentum/score yourself)                                 | `summary` block included per company (active/new markets, momentum, expansion score, stage mix)          |
| **Use when**        | you already have resolved ids and want to seed comparable peers for one target | you're given companies by domain or LinkedIn URL and want ready-to-render comparison metrics in one call |

<Tip>
  **Building a competitor-benchmarking grid around a target company?** Use **Compare** with `seed_target` to auto-select peers. **Already have a company set** (a watchlist, a CRM import, a list of domains) **and just want the numbers?** Use **Batch Company Expansion Summaries** — it saves you re-implementing the momentum/score math client-side.
</Tip>

## A typical workflow

<Steps>
  <Step title="Discover" icon="magnifying-glass">
    Call **Expansion Search** with your filters (or a natural-language `query`) to get the companies expanding into your target market. Set `is_explain_match: true` for AI "why it matches" summaries.
  </Step>

  <Step title="Drill into a company" icon="building-magnifying-glass">
    Take a `domain_search_id` from the results and call **Company Expansion Detail** for the full read in a market — stage, presence, history, and signals.
  </Step>

  <Step title="See the activity feed (optional)" icon="timeline">
    For the rich, windowed event stream, call **Company Signal Events** with the signal types and date range you care about.
  </Step>

  <Step title="Compare or map" icon="scale-balanced">
    Use **Compare Company Expansions** for a side-by-side grid seeded from a target company, **Batch Company Expansion Summaries** when you already have a company set and want ready-made metrics, or **Expansion Rankings** to plot ranked points on a map.
  </Step>
</Steps>

## Shared filters

The discovery endpoints (**Expansion Search**, **Expansion Overview**, **Expansion Rankings**) accept the same filter vocabulary — expansion filters (stage, momentum, freshness, scope, signal types), the directed-geography pair (`froms` / `tos`), **and** the full company firmographic suite (industry, technologies, employee size, revenue, saved lists). Learn the filters once in the [Filters Overview](/en/developer-guides/filters/overview); the valid values live in [Expansion Reference](/en/api-reference/endpoint/expansions/types) and the [How Expansion Signals Work](/en/knowledge-base/concepts/how-expansion-signals-work) catalog.

<CardGroup cols={2}>
  <Card title="Using the Expansion API" icon="code" href="/en/knowledge-base/concepts/expansion-api-quickstart">
    Auth, your first calls, pagination, and reading scores.
  </Card>

  <Card title="Worked Example" icon="route" href="/en/knowledge-base/concepts/expansion-signals-example">
    A full market-to-signal walkthrough.
  </Card>
</CardGroup>