> ## 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.
# Referencia de campos de expansión
> Un diccionario campo por campo para la API de Expansión — cada filtro de solicitud y campo de respuesta, su tipo, valores permitidos y significado.
Este es el **diccionario de campos** de la API de Expansión: qué hace cada filtro de solicitud y qué significa cada campo de respuesta. Para conocer el *porqué* detrás del modelo, consulta [Cómo funcionan las señales de expansión](/es/knowledge-base/concepts/how-expansion-signals-work) y el catálogo de valores en [Cómo funcionan las señales de expansión](/es/knowledge-base/concepts/how-expansion-signals-work). Para obtener una lista siempre actualizada de los valores permitidos, llama al endpoint [Taxonomía de expansión](/es/api-reference/endpoint/expansions/types).
## Dimensiones principales
Cada expansión se describe a lo largo de unos pocos ejes independientes. No los confundas:
| Campo | Qué captura | Valores de ejemplo |
| ----------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `stage` | Hasta dónde ha avanzado una empresa en un mercado | `exploring`, `committing`, `expanding`, `scaling` |
| `presence.level` | Qué tan asentada está ya la **presencia** de la empresa, independientemente de la etapa | `established`, `emerging`, `none`, `no_data` |
| `momentum` | La **trayectoria** del movimiento en este momento | `advancing`, `steady`, `pulling_back` |
| flow | La **dirección** del movimiento entre mercados, expresada con `froms` / `tos` | saliente (`froms`), entrante (`tos`), corredor (`froms`→`tos`) |
| `freshness` | Qué tan **reciente** es la evidencia | `fresh`, `cooling`, `stale`, `cold` |
| `scope` | Si se trata de un mercado nuevo o de crecimiento dentro de una presencia existente | `entering_new_market`, `expanding_within_presence`, `established_only` |
| `expansion_score` | Un ranking ordenable de 0 a 1 sobre qué tan significativa es la expansión | `0.72` |
Los valores de `stage` son `exploring`, `committing`, `expanding` y `scaling` — Exploring, Committing, Expanding, Scaling. `established` **no** es una etapa; es un `presence.level`, por lo que filtrar `stages: ["established"]` no coincide con nada y devuelve silenciosamente resultados sin filtrar.
**Flow** (la dirección del movimiento) y `momentum` (la trayectoria) son cosas distintas. Filtrar por "empresas en avance" es `momentum: ["advancing"]`; filtrar por "empresas expandiéndose *hacia* EE. UU." es `tos: ["US"]`. No existe un campo de solicitud `direction` independiente — el flow se define enteramente mediante `froms` / `tos`.
## Filtros de solicitud
### Mercados (`froms` / `tos`)
La geografía es una relación dirigida: las empresas se expanden **desde** un origen **hacia** un destino. Dos listas expresan todos los casos — sin necesidad de un indicador de dirección separado.
| Parámetro | Tipo | Significado |
| --------------- | ---------------------- | ------------------------------------------------------------------------------------- |
| `froms` | string\[] (ISO alfa-2) | Mercados de **origen** — desde dónde se está expandiendo la empresa (su base / sede). |
| `tos` | string\[] (ISO alfa-2) | Mercados de **destino** — hacia dónde se está expandiendo la empresa. |
| `exclude_froms` | string\[] (ISO alfa-2) | Mercados de origen a excluir. |
| `exclude_tos` | string\[] (ISO alfa-2) | Mercados de destino a excluir. |
| Envías | Obtienes |
| ------------------------------ | --------------------------------------------------------------- |
| `tos: ["US"]` | Todos los que se expanden **hacia** EE. UU. (entrante). |
| `froms: ["CN"]` | Empresas chinas expandiéndose **a cualquier lugar** (saliente). |
| `froms: ["CN"]`, `tos: ["US"]` | Solo el **corredor CN → US**. |
| ninguno | Todas las expansiones, a nivel mundial. |
### Filtros de señales de expansión
| Parámetro | Tipo | Significado |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `stages` | string\[] | Filtra por una o más etapas de expansión. |
| `momentum` | string\[] | Filtra por trayectoria (`advancing`/`steady`/`pulling_back`). |
| `freshness` | string\[] | Filtra por recencia de la evidencia (`fresh`/`cooling`/`stale`/`cold`). |
| `scopes` | string\[] | Filtra por `entering_new_market` / `expanding_within_presence` / `established_only`. |
| `signal_types` | string\[] | Restringe a tipos de señal específicos (`HIRE`, `OFFICE`, `AD`, `NEWS`, `DNS`, …). |
| `signal_strengths` | string\[] | Filtra por nivel de confianza de la evidencia: `low`, `medium` o `high`. (Distinto del `signal_strength_slug` por señal, que llega hasta `very_high`). |
| `min_signal_count` | integer | Número mínimo de señales de expansión — muestra empresas con presencia intensa. |
| `ahead_of_pace` | boolean | Solo empresas que se mueven más rápido que el ritmo típico de ese mercado. |
| `only_contraction` | boolean | Solo mercados en riesgo / en contracción. |
| `min_markets` | integer | Número mínimo de mercados nuevos distintos en los que ha entrado una empresa durante la ventana de tiempo. |
### Datos firmográficos
| Parámetro | Tipo | Significado |
| --------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verticals`, `technologies` | string\[] | Filtros de industria / stack tecnológico de la empresa. |
| `employees` | number\[]\[] | Rangos de número de empleados, p. ej. `[[50, 200]]`. |
| `founded_dates` | number\[] | Rango de año de fundación `[desde, hasta]`. |
| `revenues` | number\[] | Rango de ingresos en USD `[desde, hasta]`. |
| `keywords` | string\[] | Delimitación temática mediante texto libre. |
| `companies` | string\[] | Limita a empresas específicas mediante cualquier combinación de `domain_search_id`, dominio o URL de LinkedIn (los dominios / URLs se resuelven a su empresa mejor clasificada). |
### Ventana de tiempo y búsqueda
| Parámetro | Tipo | Significado |
| -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transitioned_dates` | string\[] | Ventana de señal/transición como un rango ISO `[desde, hasta]`. |
| `window_days` | integer | Ventana móvil en días, usada cuando no se proporciona `transitioned_dates`. |
| `query` | string | Búsqueda en lenguaje natural — Pubrio la interpreta como filtros (que se reflejan en `filters`). |
| `is_explain_match` | boolean | Agrega un `match_summary` generado por IA por empresa, fundamentado en sus señales reales. El número de señales citadas y el tamaño del lote escalan con `per_page`; las fuentes de alto volumen (publicaciones de empleo, campañas publicitarias) se resumen como un conteo en lugar de listarse individualmente. |
| `sort_by` | string | Orden de los resultados: `recent`, `expansion_score`, `signal_count` o `company_ranking`. Omítelo para usar el orden de relevancia predeterminado — primero los pares corroborados (2 o más tipos de señal distintos), luego los pares con evidencia repetida (3 o más señales), los más recientes primero dentro de cada nivel. Usa `recent` para pura recencia. |
## Campos de respuesta
### `stage` por empresa / por mercado
| Campo | Significado |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stage.slug` | La etapa actual (`exploring` … `scaling`). |
| `stage.expansion_score` | Ranking ordenable de significancia de 0 a 1. |
| `stage.scope` | Mercado nuevo vs. dentro de la presencia existente. |
| `stage.direction` | Trayectoria de la etapa: `advancing`, `steady`, `retreating` o `new`. Es la vista en la respuesta del mismo eje de **trayectoria** que filtras con el parámetro de solicitud `momentum` — ambos usan conjuntos de valores diferentes, así que asígnalos correctamente. |
| `stage.freshness` | Nivel de recencia de la evidencia más reciente. |
| `stage.signal_count` | Número de señales de expansión activas en este mercado. |
| `stage.first_signal_at` / `latest_signal_at` / `last_transition_at` | Marcas de tiempo clave. |
### Señales, presencia y explicación
| Campo | Significado |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `signals[]` | La evidencia subyacente: `signal_type`, `signal_subtype`, `signal_strength`, `polarity`, `event_date`, `source_type`, `display_label`, `evidence_url`. |
| `presence[]` | Presencia conocida en el mercado (oficinas/entidades): `presence_type`, `presence_strength`, `address`, `known_since`. |
| `timeline[]` | Historial de transiciones de etapa: `stage_slug`, `transitioned_at`, `transition_kind`. |
| `other_markets[]` | Los demás mercados activos de la empresa, cada uno con su etapa y conteos. |
| `match_summary` | *(cuando `is_explain_match: true`)* `{ text, citations }` — un "por qué coincide" generado por IA, citando las señales reales de esa empresa. Cada cita incluye un campo `count`: `null` para una señal individual real, o un entero cuando la cita es un conteo de volumen acotado a la ventana de tiempo (publicaciones de empleo, campañas publicitarias) en lugar de un evento único. |
`expansion_score` es un **ranking ordenable** (comparable entre empresas). Es distinto de la confianza del modelo, que las respuestas con clave de API incluyen solo cuando se establece `is_include_metadata: true`.