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

# 확장 API 사용하기

> 인증하고, 첫 확장 API 호출을 만들고, 결과를 페이지네이션하고, 확장 점수를 읽어보세요.

<Info>
  이 빠른 시작 가이드는 몇 번의 호출만으로 실제 확장 신호를 읽는 단계까지 안내합니다. 이미 Pubrio API 키가 있다고 가정합니다—생성하려면 [인증](/ko/api-reference/authentication)을 참고하세요.
</Info>

## 사전 준비

* Pubrio API 키([인증](/ko/api-reference/authentication) 참고).
* 회사의 `domain_search_id`. [회사 검색](/ko/api-reference/endpoint/companies/search) 엔드포인트에서 얻을 수 있습니다.

모든 확장 엔드포인트는 `POST`이며 JSON 본문을 받습니다. [인증](/ko/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단계 — 시장 전체 탐색하기

회사 중심이 아닌 시장 중심으로 작업하려면 [확장 시장 상세](/ko/api-reference/endpoint/expansions/market_lookup)를 사용하세요. 표준 `page` / `per_page` 매개변수로 페이지네이션됩니다.

지리는 방향이 있는 **from → to** 관계로, 두 개의 목록으로 표현합니다: `froms`(출발 / 본사 시장)와 `tos`(도착 시장). 질문에 맞는 패턴을 선택하세요:

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

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

  ```bash Corridor(CN → GB) theme={null}
  POST /expansions/lookup
  {
    "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`는 플랜에 따라 상한이 정해집니다.

## 4단계 — 증거로 드릴다운하기

회사의 움직임 뒤에 있는 개별 신호를 원할 때는 [회사 신호 이벤트](/ko/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`인 동안 계속).

## 필터링 참조

대부분의 확장 엔드포인트는 다음 필터를 받습니다. 유효한 값은 [확장 신호의 작동 원리](/ko/knowledge-base/concepts/how-expansion-signals-work)에 나열되어 있습니다.

| 필터             | 목적                                                           |
| -------------- | ------------------------------------------------------------ |
| `stages`       | 하나 이상의 확장 단계로 제한.                                            |
| `freshness`    | 증거의 최신성으로 제한.                                                |
| `momentum`     | 궤적(`accelerating`/`advancing`/`steady`/`pulling_back`)으로 제한. |
| `scopes`       | 시장 진입 범위로 제한.                                                |
| `signal_types` | 특정 신호 유형으로 제한.                                               |
| `froms`        | 출발 / 본사 시장(**여기서** 확장).                                      |
| `tos`          | 타깃 시장(**여기로** 확장).                                           |
| `companies`    | `domain_search_id`, 도메인 또는 LinkedIn URL로 특정 기업으로 범위 지정.      |

`companies` 필터는 식별자 유형의 임의 조합을 받습니다—먼저 ID로 해석할 필요가 없습니다:

<CodeGroup>
  ```bash 도메인으로 theme={null}
  POST /expansions/lookup
  { "companies": ["stripe.com", "airbnb.com"] }
  ```

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

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

<Warning>
  **흐름**과 **궤적**을 혼동하지 마세요. 흐름(시장 간 움직임의 방향)은 `froms` / `tos`로 설정합니다—`direction` 요청 필터는 없습니다. 궤적(움직임이 어떻게 진행되는지)은 `momentum` 필터이며, 응답에서는 `direction` 필드로 나타납니다.
</Warning>

## 다음 단계

<CardGroup cols={2}>
  <Card title="실전 예제" href="/ko/knowledge-base/concepts/expansion-signals-example">
    시장에서 신호까지의 전체 가이드.
  </Card>

  <Card title="확장 엔드포인트" href="/ko/api-reference/endpoint/expansions/dashboard">
    모든 확장 API 엔드포인트를 둘러보세요.
  </Card>
</CardGroup>