> ## 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.
# Referência de Campos da Expansion
> Um dicionário campo a campo para a Expansion API — todo filtro de requisição e campo de resposta, seu tipo, valores permitidos e significado.
Este é o **dicionário de campos** da Expansion API: o que cada filtro de requisição faz e o que cada campo de resposta significa. Para entender o *porquê* por trás do modelo, veja [How Expansion Signals Work](/pt/knowledge-base/concepts/how-expansion-signals-work) e o catálogo de valores em [How Expansion Signals Work](/pt/knowledge-base/concepts/how-expansion-signals-work). Para uma lista sempre atualizada dos valores permitidos, chame o endpoint [Expansion Taxonomy](/pt/api-reference/endpoint/expansions/types).
## Dimensões principais
Toda expansão é descrita ao longo de alguns eixos independentes. Não os confunda:
| Campo | O que captura | Valores de exemplo |
| ----------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `stage` | O quanto uma empresa avançou em um mercado | `exploring`, `committing`, `expanding`, `scaling` |
| `presence.level` | O quão consolidada já é a **presença** da empresa, independentemente do estágio | `established`, `emerging`, `none`, `no_data` |
| `momentum` | A **trajetória** do movimento neste momento | `advancing`, `steady`, `pulling_back` |
| flow | A **direção** do movimento entre mercados, expressa com `froms` / `tos` | saída (`froms`), entrada (`tos`), corredor (`froms`→`tos`) |
| `freshness` | O quão **recente** é a evidência | `fresh`, `cooling`, `stale`, `cold` |
| `scope` | Se é um novo mercado ou crescimento dentro de uma presença já existente | `entering_new_market`, `expanding_within_presence`, `established_only` |
| `expansion_score` | Uma classificação ordenável de 0 a 1 sobre o quão significativa é a expansão | `0.72` |
Os slugs de estágio são `exploring`, `committing`, `expanding` e `scaling` — Exploring, Committing, Expanding, Scaling. `established` **não** é um estágio; é um `presence.level`, então filtrar por `stages: ["established"]` não corresponde a nada e retorna silenciosamente resultados sem filtro.
**Flow** (a direção do movimento) e `momentum` (a trajetória) são coisas diferentes. Filtrar por "empresas avançando" é `momentum: ["advancing"]`; filtrar por "empresas se expandindo *para* os EUA" é `tos: ["US"]`. Não existe um campo de requisição `direction` separado — o flow é definido inteiramente por `froms` / `tos`.
## Filtros de requisição
### Mercados (`froms` / `tos`)
Geografia é uma relação direcionada: empresas se expandem **de** uma origem **para** um destino. Duas listas expressam todos os casos — sem uma flag de direção separada.
| Parâmetro | Tipo | Significado |
| --------------- | ----------------------- | ---------------------------------------------------------------------------------- |
| `froms` | string\[] (ISO alpha-2) | Mercados de **origem** — de onde a empresa está se expandindo (sua sede / matriz). |
| `tos` | string\[] (ISO alpha-2) | Mercados de **destino** — para onde a empresa está se expandindo. |
| `exclude_froms` | string\[] (ISO alpha-2) | Mercados de origem a excluir. |
| `exclude_tos` | string\[] (ISO alpha-2) | Mercados de destino a excluir. |
| Você envia | Você recebe |
| ------------------------------ | ---------------------------------------------------------------- |
| `tos: ["US"]` | Todos que estão se expandindo **para** os EUA (entrada). |
| `froms: ["CN"]` | Empresas chinesas se expandindo **para qualquer lugar** (saída). |
| `froms: ["CN"]`, `tos: ["US"]` | Apenas o **corredor CN → US**. |
| nenhum | Todas as expansões, no mundo todo. |
### Filtros de sinais de expansão
| Parâmetro | Tipo | Significado |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `stages` | string\[] | Limita a um ou mais estágios de expansão. |
| `momentum` | string\[] | Limita pela trajetória (`advancing`/`steady`/`pulling_back`). |
| `freshness` | string\[] | Limita pela atualidade da evidência (`fresh`/`cooling`/`stale`/`cold`). |
| `scopes` | string\[] | Limita por `entering_new_market` / `expanding_within_presence` / `established_only`. |
| `signal_types` | string\[] | Restringe a tipos de sinal específicos (`HIRE`, `OFFICE`, `AD`, `NEWS`, `DNS`, …). |
| `signal_strengths` | string\[] | Filtra por faixa de confiança da evidência: `low`, `medium` ou `high`. (Diferente do `signal_strength_slug` por sinal, que vai até `very_high`.) |
| `min_signal_count` | integer | Número mínimo de sinais de expansão — destaca movimentos com pegada intensa. |
| `ahead_of_pace` | boolean | Apenas empresas se movendo mais rápido que o ritmo típico daquele mercado. |
| `only_contraction` | boolean | Apenas mercados em risco / em retração. |
| `min_markets` | integer | Número mínimo de novos mercados distintos que uma empresa entrou na janela. |
### Firmográficos
| Parâmetro | Tipo | Significado |
| --------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verticals`, `technologies` | string\[] | Filtros de indústria / stack de tecnologia da empresa. |
| `employees` | number\[]\[] | Faixas de número de funcionários, por exemplo `[[50, 200]]`. |
| `founded_dates` | number\[] | Faixa de ano de fundação `[de, até]`. |
| `revenues` | number\[] | Faixa de receita em USD `[de, até]`. |
| `keywords` | string\[] | Delimitação de tema por texto livre. |
| `companies` | string\[] | Restringe a empresas específicas por qualquer combinação de `domain_search_id`, domínio ou URL do LinkedIn (domínios / URLs são resolvidos para a empresa de melhor classificação). |
### Janela de tempo e busca
| Parâmetro | Tipo | Significado |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transitioned_dates` | string\[] | Janela de sinal/transição como uma faixa ISO `[de, até]`. |
| `window_days` | integer | Janela móvel em dias, usada quando `transitioned_dates` não é informado. |
| `query` | string | Busca em linguagem natural — a Pubrio a interpreta em filtros (ecoada de volta em `filters`). |
| `is_explain_match` | boolean | Adiciona um `match_summary` de IA por empresa, fundamentado em seus sinais reais. A contagem de sinais citados e o tamanho do lote escalam com `per_page`; fontes de alto volume (vagas de emprego, campanhas de anúncios) são resumidas como uma contagem em vez de listadas individualmente. |
| `sort_by` | string | Ordenação dos resultados: `recent`, `expansion_score`, `signal_count` ou `company_ranking`. Omita para a ordem de relevância padrão — pares corroborados (2+ tipos de sinal distintos) primeiro, depois pares com evidência repetida (3+ sinais), mais recentes primeiro dentro de cada nível. Use `recent` para pura recência. |
## Campos de resposta
### `stage` por empresa / por mercado
| Campo | Significado |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `stage.slug` | O estágio atual (`exploring` … `scaling`). |
| `stage.expansion_score` | Classificação ordenável de significância de 0 a 1. |
| `stage.scope` | Novo mercado vs. dentro de uma presença já existente. |
| `stage.direction` | Trajetória do estágio: `advancing`, `steady`, `retreating` ou `new`. Esta é a visão do lado da resposta do mesmo eixo de **trajetória** que você filtra com o parâmetro de requisição `momentum` — os dois usam conjuntos de valores diferentes, então mapeie de acordo. |
| `stage.freshness` | Faixa de atualidade da evidência mais recente. |
| `stage.signal_count` | Número de sinais de expansão ativos nesse mercado. |
| `stage.first_signal_at` / `latest_signal_at` / `last_transition_at` | Marcações de tempo importantes. |
### Sinais, presença e explicação
| Campo | Significado |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `signals[]` | A evidência subjacente: `signal_type`, `signal_subtype`, `signal_strength`, `polarity`, `event_date`, `source_type`, `display_label`, `evidence_url`. |
| `presence[]` | Pegada conhecida no mercado (escritórios/entidades): `presence_type`, `presence_strength`, `address`, `known_since`. |
| `timeline[]` | Histórico de transição de estágios: `stage_slug`, `transitioned_at`, `transition_kind`. |
| `other_markets[]` | Os outros mercados ativos da empresa, cada um com seu estágio + contagens. |
| `match_summary` | *(quando `is_explain_match: true`)* `{ text, citations }` — um "por que corresponde" gerado por IA, citado a partir dos sinais reais dessa empresa. Cada citação carrega um campo `count`: `null` para um sinal individual real, ou um número inteiro quando a citação é uma contagem de volume delimitada por janela (vagas de emprego, campanhas de anúncios) em vez de um evento único. |
`expansion_score` é uma **classificação ordenável** (comparável entre empresas). É diferente da confiança do modelo, que as respostas com chave de API incluem apenas quando `is_include_metadata: true` está definido.