> ## 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 API — каждый фильтр запроса и поле ответа, его тип, допустимые значения и значение.
Это **словарь полей** для Expansion API: что делает каждый фильтр запроса и что означает каждое поле ответа. О *причинах*, стоящих за моделью, см. [Как работают сигналы экспансии](/ru/knowledge-base/concepts/how-expansion-signals-work) и каталог значений там же. Для всегда актуального списка допустимых значений вызовите эндпоинт [Expansion Taxonomy](/ru/api-reference/endpoint/expansions/types).
## Основные измерения
Каждая экспансия описывается по нескольким независимым осям. Не путайте их:
| Поле | Что отражает | Примеры значений |
| ----------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `stage` | Насколько далеко продвинулась компания на рынке | `exploring`, `committing`, `expanding`, `scaling` |
| `presence.level` | Насколько устоявшимся уже является **след** компании, независимо от стадии | `established`, `emerging`, `none`, `no_data` |
| `momentum` | **Траектория** движения прямо сейчас | `advancing`, `steady`, `pulling_back` |
| flow (поток) | **Направление** движения между рынками, выражается через `froms` / `tos` | исходящий (`froms`), входящий (`tos`), коридор (`froms`→`tos`) |
| `freshness` | Насколько **недавние** доказательства | `fresh`, `cooling`, `stale`, `cold` |
| `scope` | Новый ли это рынок или рост в рамках существующего присутствия | `entering_new_market`, `expanding_within_presence`, `established_only` |
| `expansion_score` | Сортируемый ранг от 0 до 1, насколько значима экспансия | `0.72` |
Slug стадий — это `exploring`, `committing`, `expanding` и `scaling` — изучение, закрепление, расширение, масштабирование. `established` — это **не** стадия; это `presence.level`, поэтому фильтрация `stages: ["established"]` ничего не находит и молча возвращает нефильтрованные результаты.
**Поток** (направление движения) и `momentum` (траектория) — разные вещи. Фильтрация «компании, ускоряющиеся» — это `momentum: ["advancing"]`; фильтрация «компании, выходящие *на* рынок США» — это `tos: ["US"]`. Отдельного поля запроса `direction` не существует — поток полностью задаётся через `froms` / `tos`.
## Фильтры запроса
### Рынки (`froms` / `tos`)
География — это направленное отношение: компании расширяются **из** источника **на** целевой рынок. Два списка выражают любой случай — без отдельного флага направления.
| Параметр | Тип | Значение |
| --------------- | ----------------------- | -------------------------------------------------------------------------- |
| `froms` | string\[] (ISO alpha-2) | **Исходные** рынки — откуда компания расширяется (её дом / штаб-квартира). |
| `tos` | string\[] (ISO alpha-2) | **Целевые** рынки — куда компания расширяется. |
| `exclude_froms` | string\[] (ISO alpha-2) | Исходные рынки для исключения. |
| `exclude_tos` | string\[] (ISO alpha-2) | Целевые рынки для исключения. |
| Вы отправляете | Вы получаете |
| ------------------------------ | -------------------------------------------------------------------- |
| `tos: ["US"]` | Всех, кто расширяется **на** рынок США (входящий поток). |
| `froms: ["CN"]` | Китайские компании, расширяющиеся **куда угодно** (исходящий поток). |
| `froms: ["CN"]`, `tos: ["US"]` | Только **коридор CN → US**. |
| ни то, ни другое | Все экспансии по всему миру. |
### Фильтры сигналов экспансии
| Параметр | Тип | Значение |
| ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stages` | string\[] | Фильтр по одной или нескольким стадиям экспансии. |
| `momentum` | string\[] | Фильтр по траектории (`advancing`/`steady`/`pulling_back`). |
| `freshness` | string\[] | Фильтр по свежести доказательств (`fresh`/`cooling`/`stale`/`cold`). |
| `scopes` | string\[] | Фильтр по `entering_new_market` / `expanding_within_presence` / `established_only`. |
| `signal_types` | string\[] | Ограничение конкретными типами сигналов (`HIRE`, `OFFICE`, `AD`, `NEWS`, `DNS`, …). |
| `signal_strengths` | string\[] | Фильтр по категории уверенности в доказательствах: `low`, `medium` или `high`. (Отличается от `signal_strength_slug` для отдельного сигнала, который доходит до `very_high`.) |
| `min_signal_count` | integer | Минимальное число сигналов экспансии — отражает компании с обширным следом. |
| `ahead_of_pace` | boolean | Только компании, движущиеся быстрее типичного темпа для этого рынка. |
| `only_contraction` | boolean | Только рискованные / сокращающиеся рынки. |
| `min_markets` | integer | Минимальное число новых рынков, на которые компания вышла за окно. |
### Фирмографика
| Параметр | Тип | Значение |
| --------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `verticals`, `technologies` | string\[] | Фильтры по отрасли / технологическому стеку компании. |
| `employees` | number\[]\[] | Диапазоны числа сотрудников, например `[[50, 200]]`. |
| `founded_dates` | number\[] | Диапазон года основания `[from, to]`. |
| `revenues` | number\[] | Диапазон выручки в USD `[from, to]`. |
| `keywords` | string\[] | Ограничение по свободной текстовой теме. |
| `companies` | string\[] | Ограничение конкретными компаниями через любое сочетание `domain_search_id`, домена или URL LinkedIn (домены/URL разрешаются в компанию с наивысшим рангом). |
### Временное окно и поиск
| Параметр | Тип | Значение |
| -------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transitioned_dates` | string\[] | Окно сигнала/перехода как диапазон ISO `[from, to]`. |
| `window_days` | integer | Скользящее окно в днях, используется, когда `transitioned_dates` не передан. |
| `query` | string | Поиск на естественном языке — Pubrio интерпретирует его в фильтры (отражается обратно в `filters`). |
| `is_explain_match` | boolean | Добавить AI `match_summary` для каждой компании, основанный на её реальных сигналах. Число цитируемых сигналов и размер пакета масштабируются с `per_page`; источники большого объёма (вакансии, рекламные кампании) суммируются как количество, а не перечисляются по отдельности. |
| `sort_by` | string | Порядок результатов: `recent`, `expansion_score`, `signal_count` или `company_ranking`. Опустите для порядка по релевантности по умолчанию — сначала подтверждённые пары (2+ разных типа сигнала), затем пары с повторными доказательствами (3+ сигнала), внутри каждого уровня — сначала самые новые. Используйте `recent` для чистой хронологии. |
## Поля ответа
### `stage` по компании/рынку
| Поле | Значение |
| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stage.slug` | Текущая стадия (`exploring` … `scaling`). |
| `stage.expansion_score` | Сортируемый ранг значимости от 0 до 1. |
| `stage.scope` | Новый рынок против роста в рамках присутствия. |
| `stage.direction` | Траектория стадии: `advancing`, `steady`, `retreating` или `new`. Это представление той же оси **траектории** со стороны ответа, по которой вы фильтруете через параметр запроса `momentum` — у них разные наборы значений, сопоставляйте соответственно. |
| `stage.freshness` | Категория свежести последних доказательств. |
| `stage.signal_count` | Число активных сигналов экспансии на этом рынке. |
| `stage.first_signal_at` / `latest_signal_at` / `last_transition_at` | Ключевые временные метки. |
### Сигналы, присутствие и объяснение
| Поле | Значение |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signals[]` | Лежащие в основе доказательства: `signal_type`, `signal_subtype`, `signal_strength`, `polarity`, `event_date`, `source_type`, `display_label`, `evidence_url`. |
| `presence[]` | Известный след на рынке (офисы/юрлица): `presence_type`, `presence_strength`, `address`, `known_since`. |
| `timeline[]` | История переходов между стадиями: `stage_slug`, `transitioned_at`, `transition_kind`. |
| `other_markets[]` | Другие активные рынки компании, каждый со своей стадией и счётчиками. |
| `match_summary` | *(при `is_explain_match: true`)* `{ text, citations }` — AI-объяснение «почему это совпадение», основанное на реальных сигналах этой компании. Каждая цитата несёт поле `count`: `null` для реального отдельного сигнала, либо целое число, когда цитата — это счётчик объёма в рамках окна (вакансии, рекламные кампании), а не единичное событие. |
`expansion_score` — это **сортируемый ранг** (сравнимый между компаниями). Он отличается от уверенности модели, которую ответы с API-ключом включают только при установленном `is_include_metadata: true`.