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

# Usando a Expansion API

> Autentique, faça suas primeiras chamadas à Expansion API, pagine resultados e leia scores de expansão.

<Info>
  Este guia rápido leva você do zero à leitura de sinais de expansão ao vivo em poucas chamadas. Ele pressupõe que você já tem uma chave de API da Pubrio — veja [Autenticação](/pt/api-reference/authentication) para criar uma.
</Info>

## Pré-requisitos

* Uma chave de API da Pubrio (veja [Autenticação](/pt/api-reference/authentication)).
* O `domain_search_id` de uma empresa. Você pode obter um a partir do endpoint [Company Search](/pt/api-reference/endpoint/companies/search).

Todos os endpoints de Expansion são `POST` e aceitam um corpo JSON. Inclua suas credenciais em cada requisição conforme descrito em [Autenticação](/pt/api-reference/authentication).

## Passo 1 — Consultar a expansão de uma empresa

Comece com uma única empresa e liste todos os mercados para os quais ela está se expandindo.

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

## Passo 2 — Interpretar o resultado

Cada entrada em `markets_summary` descreve um mercado no qual a empresa está ativa:

* **`stage_slug`** — o quão longe a empresa avançou ali (`exploring` → `scaling`).
* **`signal_count`** / **`distinct_type_count`** — quantas evidências sustentam o mercado, e em quantos tipos de sinal.
* **`latest_signal_at`** — a atualidade do sinal mais recente.
* **`signal_velocity_30d`** / **`signal_velocity_90d`** — a velocidade com que a atividade está aumentando.
* **`rank_now`** — a posição atual do mercado para essa empresa (`1` = mais forte).
* **`is_home_market`** — se este é o país-sede da empresa.

Para identificar os movimentos mais recentes ou filtrar por trajetória, use os endpoints de descoberta (`freshness`, `momentum`) mostrados a seguir.

## Passo 3 — Explorar um mercado inteiro

Para trabalhar primeiro pelo mercado em vez de pela empresa, use [Expansion Market Detail](/pt/api-reference/endpoint/expansions/market_lookup). Ele é paginado com os parâmetros padrão `page` / `per_page`.

Geografia é uma relação direcionada **de → para**, expressa com duas listas: `froms` (mercados de origem / sede) e `tos` (mercados de destino). Escolha o padrão que corresponde à sua pergunta:

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

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

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

Leia `metadata.pagination` para paginar pelos resultados:

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

Solicite a próxima página incrementando `page`. O `per_page` é limitado pelo seu plano — solicitar explicitamente mais do que seu limite retorna um erro em vez de truncar silenciosamente.

Dois padrões que vale a pena conhecer:

* **Ordenação** — os resultados retornam em ordem de relevância (empresas corroboradas por múltiplos tipos de sinal primeiro, depois as mais recentes). Passe `sort_by: "recent"` para ordenação puramente por data, ou `expansion_score` / `signal_count` / `company_ranking`.
* **Respostas enxutas** — respostas com chave de API omitem o resumo do mercado (`metadata.aggregate`, principais origens/destinos, timeline) e o detalhe do modelo por padrão. Passe `is_include_metadata: true` quando quiser incluí-los.

## Passo 4 — Investigar a evidência

Quando você quiser os sinais individuais por trás do movimento de uma empresa, chame [Company Signal Events](/pt/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
}
```

Esse endpoint retorna `total_entries` e `total_pages` — solicite as páginas de `1` até `total_pages` (ou seja, continue enquanto `page` for menor que `total_pages`).

## Referência de filtros

A maioria dos endpoints de Expansion aceita estes filtros. Seus valores válidos estão listados em [How Expansion Signals Work](/pt/knowledge-base/concepts/how-expansion-signals-work):

| Filtro         | Finalidade                                                                           |
| -------------- | ------------------------------------------------------------------------------------ |
| `stages`       | Limita a um ou mais estágios de expansão.                                            |
| `freshness`    | Limita pela atualidade da evidência.                                                 |
| `momentum`     | Limita pela trajetória (`advancing`/`steady`/`pulling_back`).                        |
| `scopes`       | Limita pelo escopo de entrada no mercado.                                            |
| `signal_types` | Limita a tipos de sinal específicos.                                                 |
| `froms`        | Mercados de origem / sede (expandindo **de**).                                       |
| `tos`          | Mercados de destino (expandindo **para**).                                           |
| `companies`    | Restringe a empresas específicas por `domain_search_id`, domínio ou URL do LinkedIn. |

O filtro `companies` aceita qualquer combinação de tipos de identificador — sem necessidade de resolver para IDs primeiro:

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

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

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

<Warning>
  Não confunda **fluxo** com **trajetória**. O fluxo (a direção do movimento entre mercados) é definido por `froms` / `tos` — não existe um filtro de requisição `direction` separado. A trajetória (como o movimento está progredindo) é o filtro `momentum`, e aparece nas respostas como o campo `direction`.
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Exemplo Prático" href="/pt/knowledge-base/concepts/expansion-signals-example">
    O passo a passo completo do mercado ao sinal.
  </Card>

  <Card title="Endpoints de Expansion" href="/pt/api-reference/endpoint/expansions/dashboard">
    Explore todos os endpoints da Expansion API.
  </Card>
</CardGroup>