> ## 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.
# Expansion-Feldreferenz
> Ein Feld-für-Feld-Wörterbuch für die Expansion API — jeder Anfragefilter und jedes Antwortfeld, sein Typ, erlaubte Werte und Bedeutung.
Dies ist das **Feldwörterbuch** für die Expansion API: was jeder Anfragefilter bewirkt und was jedes Antwortfeld bedeutet. Für das *Warum* hinter dem Modell siehe [Wie Expansion-Signale funktionieren](/de/knowledge-base/concepts/how-expansion-signals-work) und den Wertekatalog in [Wie Expansion-Signale funktionieren](/de/knowledge-base/concepts/how-expansion-signals-work). Für eine stets aktuelle Liste erlaubter Werte rufen Sie den Endpunkt [Expansion Taxonomy](/de/api-reference/endpoint/expansions/types) auf.
## Kerndimensionen
Jede Expansion wird entlang weniger unabhängiger Achsen beschrieben. Verwechseln Sie diese nicht:
| Feld | Was es erfasst | Beispielwerte |
| ----------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `stage` | Wie weit ein Unternehmen in einem Markt vorangeschritten ist | `exploring`, `committing`, `expanding`, `scaling` |
| `presence.level` | Wie etabliert der **Fußabdruck** des Unternehmens bereits ist, unabhängig von der Stufe | `established`, `emerging`, `none`, `no_data` |
| `momentum` | Die **Trajektorie** der Bewegung im Moment | `advancing`, `steady`, `pulling_back` |
| flow | Die **Richtung** der Bewegung zwischen Märkten, ausgedrückt mit `froms` / `tos` | outbound (`froms`), inbound (`tos`), Korridor (`froms`→`tos`) |
| `freshness` | Wie **aktuell** die Evidenz ist | `fresh`, `cooling`, `stale`, `cold` |
| `scope` | Ob es sich um einen neuen Markt oder Wachstum innerhalb einer bestehenden Präsenz handelt | `entering_new_market`, `expanding_within_presence`, `established_only` |
| `expansion_score` | Ein sortierbarer 0–1-Rang dafür, wie bedeutsam die Expansion ist | `0.72` |
Die Stufen-Slugs sind `exploring`, `committing`, `expanding` und `scaling` — Exploring, Committing, Expanding, Scaling. `established` ist **keine** Stufe; es ist ein `presence.level`, daher liefert das Filtern nach `stages: ["established"]` keine Treffer und gibt stillschweigend ungefilterte Ergebnisse zurück.
**Flow** (die Richtung der Bewegung) und `momentum` (die Trajektorie) sind unterschiedliche Dinge. Das Filtern nach „Unternehmen, die voranschreiten" ist `momentum: ["advancing"]`; das Filtern nach „Unternehmen, die *in* die USA expandieren" ist `tos: ["US"]`. Es gibt kein separates `direction`-Anfragefeld — Flow wird ausschließlich durch `froms` / `tos` festgelegt.
## Anfragefilter
### Märkte (`froms` / `tos`)
Geografie ist eine gerichtete Beziehung: Unternehmen expandieren **von** einem Ursprung **zu** einem Ziel. Zwei Listen drücken jeden Fall aus — kein separates Richtungsflag.
| Parameter | Typ | Bedeutung |
| --------------- | ----------------------- | ------------------------------------------------------------------------------------ |
| `froms` | string\[] (ISO alpha-2) | **Ursprungs**-Märkte — von wo aus das Unternehmen expandiert (sein Heimat-/HQ-Land). |
| `tos` | string\[] (ISO alpha-2) | **Ziel**-Märkte — wohin das Unternehmen expandiert. |
| `exclude_froms` | string\[] (ISO alpha-2) | Auszuschließende Ursprungsmärkte. |
| `exclude_tos` | string\[] (ISO alpha-2) | Auszuschließende Zielmärkte. |
| Sie senden | Sie erhalten |
| ------------------------------ | ------------------------------------------------------------------- |
| `tos: ["US"]` | Alle, die **in** die USA expandieren (inbound). |
| `froms: ["CN"]` | Chinesische Unternehmen, die **überallhin** expandieren (outbound). |
| `froms: ["CN"]`, `tos: ["US"]` | Nur den **CN → US**-Korridor. |
| keins von beiden | Alle Expansionen weltweit. |
### Expansion-Signalfilter
| Parameter | Typ | Bedeutung |
| ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stages` | string\[] | Auf eine oder mehrere Expansion-Stufen beschränken. |
| `momentum` | string\[] | Nach Trajektorie filtern (`advancing`/`steady`/`pulling_back`). |
| `freshness` | string\[] | Nach Aktualität der Evidenz filtern (`fresh`/`cooling`/`stale`/`cold`). |
| `scopes` | string\[] | Nach `entering_new_market` / `expanding_within_presence` / `established_only` filtern. |
| `signal_types` | string\[] | Auf bestimmte Signaltypen beschränken (`HIRE`, `OFFICE`, `AD`, `NEWS`, `DNS`, …). |
| `signal_strengths` | string\[] | Nach Evidenz-Konfidenz-Bucket filtern: `low`, `medium` oder `high`. (Zu unterscheiden vom signalspezifischen `signal_strength_slug`, der bis `very_high` reicht.) |
| `min_signal_count` | integer | Mindestanzahl an Expansion-Signalen — macht Bewegungen mit starkem Fußabdruck sichtbar. |
| `ahead_of_pace` | boolean | Nur Unternehmen, die sich schneller bewegen als für diesen Markt typisch. |
| `only_contraction` | boolean | Nur gefährdete / schrumpfende Märkte. |
| `min_markets` | integer | Mindestanzahl unterschiedlicher neuer Märkte, die ein Unternehmen im Zeitfenster betreten hat. |
### Firmografische Daten
| Parameter | Typ | Bedeutung |
| --------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verticals`, `technologies` | string\[] | Filter nach Unternehmensbranche / Tech-Stack. |
| `employees` | number\[]\[] | Mitarbeiterzahl-Bereiche, z. B. `[[50, 200]]`. |
| `founded_dates` | number\[] | Gründungsjahr-Bereich `[von, bis]`. |
| `revenues` | number\[] | Umsatzbereich in USD `[von, bis]`. |
| `keywords` | string\[] | Freitext-Themeneingrenzung. |
| `companies` | string\[] | Auf bestimmte Unternehmen beschränken, per beliebiger Mischung aus `domain_search_id`, Domain oder LinkedIn-URL (Domains/URLs werden zum bestplatzierten Unternehmen aufgelöst). |
### Zeitfenster & Suche
| Parameter | Typ | Bedeutung |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transitioned_dates` | string\[] | Signal-/Übergangsfenster als ISO-`[von, bis]`-Bereich. |
| `window_days` | integer | Rollierendes Fenster in Tagen, verwendet, wenn `transitioned_dates` nicht angegeben ist. |
| `query` | string | Suche in natürlicher Sprache — Pubrio interpretiert sie in Filter (in `filters` gespiegelt). |
| `is_explain_match` | boolean | Fügt jedem Unternehmen eine KI-`match_summary` hinzu, die auf dessen realen Signalen basiert. Zitierte Signalanzahl und Batch-Größe skalieren mit `per_page`; Quellen mit hohem Volumen (Stellenanzeigen, Ad-Kampagnen) werden als Anzahl statt einzeln aufgelistet zusammengefasst. |
| `sort_by` | string | Ergebnissortierung: `recent`, `expansion_score`, `signal_count` oder `company_ranking`. Weglassen für die Standard-Relevanzreihenfolge — bestätigte Paare (2+ unterschiedliche Signaltypen) zuerst, dann Paare mit wiederholter Evidenz (3+ Signale), innerhalb jeder Stufe die aktuellsten zuerst. Verwenden Sie `recent` für reine Aktualität. |
## Antwortfelder
### `stage` pro Unternehmen/Markt
| Feld | Bedeutung |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stage.slug` | Die aktuelle Stufe (`exploring` … `scaling`). |
| `stage.expansion_score` | Sortierbarer 0–1-Bedeutsamkeitsrang. |
| `stage.scope` | Neuer Markt vs. innerhalb bestehender Präsenz. |
| `stage.direction` | Trajektorie der Stufe: `advancing`, `steady`, `retreating` oder `new`. Dies ist die antwortseitige Sicht auf dieselbe **Trajektorie**-Achse, nach der Sie mit dem `momentum`-Anfrageparameter filtern — beide verwenden unterschiedliche Wertesätze, ordnen Sie entsprechend zu. |
| `stage.freshness` | Aktualitäts-Bucket der neuesten Evidenz. |
| `stage.signal_count` | Anzahl aktiver Expansion-Signale in diesem Markt. |
| `stage.first_signal_at` / `latest_signal_at` / `last_transition_at` | Wichtige Zeitstempel. |
### Signale, Präsenz & Erklärung
| Feld | Bedeutung |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signals[]` | Die zugrunde liegende Evidenz: `signal_type`, `signal_subtype`, `signal_strength`, `polarity`, `event_date`, `source_type`, `display_label`, `evidence_url`. |
| `presence[]` | Bekannter Fußabdruck im Markt (Büros/Entitäten): `presence_type`, `presence_strength`, `address`, `known_since`. |
| `timeline[]` | Historie der Stufenübergänge: `stage_slug`, `transitioned_at`, `transition_kind`. |
| `other_markets[]` | Die anderen aktiven Märkte des Unternehmens, jeweils mit Stufe + Zählwerten. |
| `match_summary` | *(wenn `is_explain_match: true`)* `{ text, citations }` — ein KI-„Warum es passt", zitiert auf die realen Signale dieses Unternehmens. Jede Zitation trägt ein `count`-Feld: `null` für ein echtes einzelnes Signal, oder eine Ganzzahl, wenn die Zitation eine fensterbezogene Volumenanzahl ist (Stellenanzeigen, Ad-Kampagnen) statt eines einzelnen Ereignisses. |
`expansion_score` ist ein **sortierbarer Rang** (unternehmensübergreifend vergleichbar). Er unterscheidet sich von der Modell-Konfidenz, die API-Key-Antworten nur enthalten, wenn `is_include_metadata: true` gesetzt ist.