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

# Die Expansion API verwenden

> Authentifizieren Sie sich, führen Sie Ihre ersten Expansion-API-Aufrufe aus, paginieren Sie Ergebnisse und lesen Sie Expansion-Scores.

<Info>
  Dieser Schnelleinstieg bringt Sie in wenigen Aufrufen von null zum Lesen live erfasster Expansion-Signale. Es wird vorausgesetzt, dass Sie bereits über einen Pubrio-API-Key verfügen — siehe [Authentifizierung](/de/api-reference/authentication), um einen zu erstellen.
</Info>

## Voraussetzungen

* Ein Pubrio-API-Key (siehe [Authentifizierung](/de/api-reference/authentication)).
* Die `domain_search_id` eines Unternehmens. Sie erhalten diese über den Endpunkt [Company Search](/de/api-reference/endpoint/companies/search).

Alle Expansion-Endpunkte sind `POST`-Anfragen und akzeptieren einen JSON-Body. Fügen Sie Ihre Zugangsdaten wie in [Authentifizierung](/de/api-reference/authentication) beschrieben bei jeder Anfrage bei.

## Schritt 1 — Die Expansion eines Unternehmens nachschlagen

Beginnen Sie mit einem einzelnen Unternehmen und listen Sie jeden Markt auf, in den es expandiert.

```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 }
  ]
}
```

## Schritt 2 — Das Ergebnis lesen

Jeder Eintrag in `markets_summary` beschreibt einen Markt, in dem das Unternehmen aktiv ist:

* **`stage_slug`** — wie weit das Unternehmen dort vorangeschritten ist (`exploring` → `scaling`).
* **`signal_count`** / **`distinct_type_count`** — wie viel Evidenz den Markt untermauert, über wie viele Signaltypen hinweg.
* **`latest_signal_at`** — Aktualität des neuesten Signals.
* **`signal_velocity_30d`** / **`signal_velocity_90d`** — wie schnell die Aktivität zunimmt.
* **`rank_now`** — der aktuelle Rang des Marktes für dieses Unternehmen (`1` = am stärksten).
* **`is_home_market`** — ob dies das Heimatland des Unternehmenssitzes ist.

Um die aktuellsten Bewegungen sichtbar zu machen oder nach Trajektorie zu filtern, nutzen Sie die im Folgenden gezeigten Discovery-Endpunkte (`freshness`, `momentum`).

## Schritt 3 — Einen ganzen Markt erkunden

Um marktorientiert statt unternehmensorientiert zu arbeiten, nutzen Sie [Expansion Market Detail](/de/api-reference/endpoint/expansions/market_lookup). Er wird mit den Standardparametern `page` / `per_page` paginiert.

Geografie ist eine gerichtete **von → nach**-Beziehung, ausgedrückt mit zwei Listen: `froms` (Ursprungs-/HQ-Märkte) und `tos` (Zielmärkte). Wählen Sie das Muster, das zu Ihrer Frage passt:

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

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

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

Lesen Sie `metadata.pagination`, um durch die Ergebnisse zu blättern:

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

Fordern Sie die nächste Seite an, indem Sie `page` erhöhen. `per_page` ist durch Ihren Plan begrenzt — eine explizite Anfrage über Ihr Limit hinaus liefert einen Fehler, statt stillschweigend zu kürzen.

Zwei Standardwerte, die Sie kennen sollten:

* **Sortierung** — Ergebnisse werden standardmäßig in Relevanzreihenfolge zurückgegeben (Unternehmen, die durch mehrere Signaltypen bestätigt werden, zuerst, dann die aktuellsten). Übergeben Sie `sort_by: "recent"` für reine Aktualität oder `expansion_score` / `signal_count` / `company_ranking`.
* **Schlanke Antworten** — Antworten mit API-Key lassen standardmäßig das Markt-Rollup (`metadata.aggregate`, Top-Ursprünge/-Ziele, Timeline) und Modelldetails aus. Übergeben Sie `is_include_metadata: true`, wenn Sie diese benötigen.

## Schritt 4 — In die Evidenz eintauchen

Wenn Sie die einzelnen Signale hinter der Bewegung eines Unternehmens sehen möchten, rufen Sie [Company Signal Events](/de/api-reference/endpoint/expansions/company_pulse_events) auf.

```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
}
```

Dieser Endpunkt gibt `total_entries` und `total_pages` zurück — fordern Sie die Seiten `1` bis `total_pages` an (d. h. fahren Sie fort, solange `page` \< `total_pages`).

## Filter-Referenz

Die meisten Expansion-Endpunkte akzeptieren diese Filter. Ihre gültigen Werte sind in [Wie Expansion-Signale funktionieren](/de/knowledge-base/concepts/how-expansion-signals-work) aufgeführt:

| Filter         | Zweck                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------- |
| `stages`       | Auf eine oder mehrere Expansion-Stufen beschränken.                                      |
| `freshness`    | Nach Aktualität der Evidenz beschränken.                                                 |
| `momentum`     | Nach Trajektorie beschränken (`advancing`/`steady`/`pulling_back`).                      |
| `scopes`       | Nach Umfang des Markteintritts beschränken.                                              |
| `signal_types` | Auf bestimmte Signaltypen beschränken.                                                   |
| `froms`        | Ursprungs-/HQ-Märkte (Expansion **von**).                                                |
| `tos`          | Zielmärkte (Expansion **in**).                                                           |
| `companies`    | Auf bestimmte Unternehmen nach `domain_search_id`, Domain oder LinkedIn-URL beschränken. |

Der `companies`-Filter akzeptiert jede Mischung von Identifikatortypen — keine vorherige Auflösung zu IDs erforderlich:

<CodeGroup>
  ```bash Nach Domain theme={null}
  POST /expansions/search
  { "companies": ["stripe.com", "airbnb.com"] }
  ```

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

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

<Warning>
  Verwechseln Sie **Flow** nicht mit **Trajektorie**. Flow (die Richtung der Bewegung zwischen Märkten) wird durch `froms` / `tos` festgelegt — es gibt keinen `direction`-Anfragefilter. Trajektorie (wie sich die Bewegung entwickelt) ist der `momentum`-Filter und erscheint in Antworten als `direction`-Feld.
</Warning>

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Durchgerechnetes Beispiel" href="/de/knowledge-base/concepts/expansion-signals-example">
    Der vollständige Market-to-Signal-Durchlauf.
  </Card>

  <Card title="Expansion-Endpunkte" href="/de/api-reference/endpoint/expansions/dashboard">
    Durchsuchen Sie jeden Endpunkt der Expansion API.
  </Card>
</CardGroup>