> ## 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, пагинируйте результаты и читайте оценки экспансии.

<Info>
  Это краткое руководство доведёт вас от нуля до чтения живых сигналов экспансии за несколько вызовов. Предполагается, что у вас уже есть ключ API Pubrio — см. [Аутентификация](/ru/api-reference/authentication), чтобы его создать.
</Info>

## Предварительные требования

* Ключ API Pubrio (см. [Аутентификация](/ru/api-reference/authentication)).
* `domain_search_id` компании. Вы можете получить его через эндпоинт [Company Search](/ru/api-reference/endpoint/companies/search).

Все эндпоинты Expansion — это `POST`, принимающие JSON-тело. Включайте свои учётные данные в каждый запрос, как описано в [Аутентификация](/ru/api-reference/authentication).

## Шаг 1 — просмотрите экспансию компании

Начните с одной компании и перечислите каждый рынок, на который она выходит.

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

## Шаг 2 — прочитайте результат

Каждая запись в `markets_summary` описывает один рынок, на котором компания активна:

* **`stage_slug`** — насколько далеко компания продвинулась там (`exploring` → `scaling`).
* **`signal_count`** / **`distinct_type_count`** — сколько доказательств подкрепляет рынок, по скольким типам сигналов.
* **`latest_signal_at`** — свежесть самого нового сигнала.
* **`signal_velocity_30d`** / **`signal_velocity_90d`** — насколько быстро набирает обороты активность.
* **`rank_now`** — текущий ранг рынка для этой компании (`1` = самый сильный).
* **`is_home_market`** — является ли это страной штаб-квартиры компании.

Чтобы отразить самые свежие движения или отфильтровать по траектории, используйте эндпоинты обнаружения (`freshness`, `momentum`), показанные далее.

## Шаг 3 — исследуйте целый рынок

Чтобы работать сначала с рынком, а не с компанией, используйте [Expansion Market Detail](/ru/api-reference/endpoint/expansions/market_lookup). Он постраничный, со стандартными параметрами `page` / `per_page`.

География — это направленное отношение **из → в**, выражаемое двумя списками: `froms` (исходные рынки / штаб-квартира) и `tos` (целевые рынки). Выберите паттерн, соответствующий вашему вопросу:

<CodeGroup>
  ```bash Входящий поток (на GB) theme={null}
  POST /expansions/search
  {
    "tos": ["GB"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

  ```bash Исходящий поток (из CN) theme={null}
  POST /expansions/search
  {
    "froms": ["CN"],
    "freshness": ["fresh", "cooling"],
    "page": 1,
    "per_page": 25
  }
  ```

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

Прочитайте `metadata.pagination`, чтобы листать результаты постранично:

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

Запросите следующую страницу, увеличивая `page`. `per_page` ограничен вашим тарифом — явный запрос больше вашего лимита возвращает ошибку, а не молчаливое усечение.

Два значения по умолчанию, о которых стоит знать:

* **Порядок** — результаты возвращаются в порядке релевантности (сначала компании, подтверждённые несколькими типами сигналов, затем самые свежие). Передайте `sort_by: "recent"` для чистой хронологии, либо `expansion_score` / `signal_count` / `company_ranking`.
* **Облегчённые ответы** — ответы с API-ключом по умолчанию опускают сводку по рынку (`metadata.aggregate`, топ источников/назначений, временную шкалу) и детали модели. Передайте `is_include_metadata: true`, когда они вам нужны.

## Шаг 4 — углубитесь в доказательства

Когда вам нужны отдельные сигналы, стоящие за движением компании, вызовите [Company Signal Events](/ru/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
}
```

Этот эндпоинт возвращает `total_entries` и `total_pages` — запрашивайте страницы с `1` по `total_pages` (то есть продолжайте, пока `page` \< `total_pages`).

## Справочник фильтрации

Большинство эндпоинтов экспансии принимают эти фильтры. Их допустимые значения перечислены в [Как работают сигналы экспансии](/ru/knowledge-base/concepts/how-expansion-signals-work):

| Фильтр         | Назначение                                                                        |
| -------------- | --------------------------------------------------------------------------------- |
| `stages`       | Ограничить одной или несколькими стадиями экспансии.                              |
| `freshness`    | Ограничить по свежести доказательств.                                             |
| `momentum`     | Ограничить по траектории (`advancing`/`steady`/`pulling_back`).                   |
| `scopes`       | Ограничить по области охвата выхода на рынок.                                     |
| `signal_types` | Ограничить конкретными типами сигналов.                                           |
| `froms`        | Исходные рынки / штаб-квартира (расширение **из**).                               |
| `tos`          | Целевые рынки (расширение **на**).                                                |
| `companies`    | Ограничить конкретными компаниями по `domain_search_id`, домену или URL LinkedIn. |

Фильтр `companies` принимает любое сочетание типов идентификаторов — не нужно сначала разрешать их в ID:

<CodeGroup>
  ```bash По домену theme={null}
  POST /expansions/search
  { "companies": ["stripe.com", "airbnb.com"] }
  ```

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

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

<Warning>
  Не путайте **поток** с **траекторией**. Поток (направление движения между рынками) задаётся через `froms` / `tos` — фильтра запроса `direction` не существует. Траектория (то, как прогрессирует движение) — это фильтр `momentum`, и он отражается в ответах как поле `direction`.
</Warning>

## Следующие шаги

<CardGroup cols={2}>
  <Card title="Разобранный пример" href="/ru/knowledge-base/concepts/expansion-signals-example">
    Полный разбор пути от рынка к сигналу.
  </Card>

  <Card title="Эндпоинты экспансии" href="/ru/api-reference/endpoint/expansions/dashboard">
    Просмотрите каждый эндпоинт Expansion API.
  </Card>
</CardGroup>