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

# Usar la API de expansión

> Autentícate, realiza tus primeras llamadas a la API de expansión, pagina resultados y lee las puntuaciones de expansión.

<Info>
  Esta guía rápida te lleva de cero a leer señales de expansión en vivo en unas pocas llamadas. Se asume que ya tienes una clave de API de Pubrio — consulta [Autenticación](/es/api-reference/authentication) para crear una.
</Info>

## Requisitos previos

* Una clave de API de Pubrio (consulta [Autenticación](/es/api-reference/authentication)).
* El `domain_search_id` de una empresa. Puedes obtenerlo desde el endpoint de [búsqueda de empresas](/es/api-reference/endpoint/companies/search).

Todos los endpoints de expansión son `POST` y aceptan un cuerpo JSON. Incluye tus credenciales en cada solicitud tal como se describe en [Autenticación](/es/api-reference/authentication).

## Paso 1 — Consultar la expansión de una empresa

Empieza con una sola empresa y lista todos los mercados en los que se está expandiendo.

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

## Paso 2 — Leer el resultado

Cada entrada en `markets_summary` describe un mercado en el que la empresa está activa:

* **`stage_slug`** — hasta dónde ha avanzado la empresa en ese mercado (`exploring` → `scaling`).
* **`signal_count`** / **`distinct_type_count`** — cuánta evidencia respalda el mercado, en cuántos tipos de señal.
* **`latest_signal_at`** — la antigüedad de la señal más reciente.
* **`signal_velocity_30d`** / **`signal_velocity_90d`** — con qué rapidez está aumentando la actividad.
* **`rank_now`** — la posición actual del mercado para esta empresa (`1` = la más fuerte).
* **`is_home_market`** — si este es el país de la sede de la empresa.

Para identificar los movimientos más recientes o filtrar por trayectoria, usa los endpoints de descubrimiento (`freshness`, `momentum`) que se muestran a continuación.

## Paso 3 — Explorar un mercado completo

Para trabajar primero por mercado en lugar de por empresa, usa [Detalle de expansión de mercado](/es/api-reference/endpoint/expansions/market_lookup). Está paginado con los parámetros estándar `page` / `per_page`.

La geografía es una relación dirigida **de → a**, expresada con dos listas: `froms` (mercados de origen / sede) y `tos` (mercados objetivo). Elige el patrón que coincida con tu pregunta:

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

  ```bash Saliente (desde 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>

Lee `metadata.pagination` para paginar los 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": [ /* ... */ ]
  }
}
```

Solicita la siguiente página incrementando `page`. `per_page` está limitado por tu plan — solicitar explícitamente más de tu límite devuelve un error en lugar de truncar silenciosamente.

Dos valores predeterminados que conviene conocer:

* **Orden** — los resultados llegan en orden de relevancia (primero las empresas corroboradas por varios tipos de señal, luego las más recientes). Pasa `sort_by: "recent"` para orden puramente cronológico, o `expansion_score` / `signal_count` / `company_ranking`.
* **Respuestas ligeras** — las respuestas con clave de API omiten por defecto el resumen del mercado (`metadata.aggregate`, principales orígenes/destinos, línea temporal) y el detalle del modelo. Pasa `is_include_metadata: true` cuando los necesites.

## Paso 4 — Profundizar en la evidencia

Cuando quieras las señales individuales detrás del movimiento de una empresa, llama a [Eventos de señales de la empresa](/es/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
}
```

Este endpoint devuelve `total_entries` y `total_pages` — solicita las páginas de la `1` a `total_pages` (es decir, continúa mientras `page` \< `total_pages`).

## Referencia de filtros

La mayoría de los endpoints de expansión aceptan estos filtros. Sus valores válidos se detallan en [Cómo funcionan las señales de expansión](/es/knowledge-base/concepts/how-expansion-signals-work):

| Filtro         | Propósito                                                                        |
| -------------- | -------------------------------------------------------------------------------- |
| `stages`       | Limita a una o más etapas de expansión.                                          |
| `freshness`    | Limita por antigüedad de la evidencia.                                           |
| `momentum`     | Limita por trayectoria (`advancing`/`steady`/`pulling_back`).                    |
| `scopes`       | Limita por alcance de entrada al mercado.                                        |
| `signal_types` | Limita a tipos de señal específicos.                                             |
| `froms`        | Mercados de origen / sede (expandiéndose **desde**).                             |
| `tos`          | Mercados objetivo (expandiéndose **hacia**).                                     |
| `companies`    | Limita a empresas específicas por `domain_search_id`, dominio o URL de LinkedIn. |

El filtro `companies` acepta cualquier combinación de tipos de identificador — no es necesario resolverlos primero a IDs:

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

  ```bash Por URL de 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>
  No confundas **flujo** con **trayectoria**. El flujo (la dirección del movimiento entre mercados) lo establecen `froms` / `tos` — no existe un filtro de solicitud `direction`. La trayectoria (cómo está progresando el movimiento) es el filtro `momentum`, y aparece en las respuestas como el campo `direction`.
</Warning>

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Ejemplo resuelto" href="/es/knowledge-base/concepts/expansion-signals-example">
    El recorrido completo de mercado a señal.
  </Card>

  <Card title="Endpoints de expansión" href="/es/api-reference/endpoint/expansions/dashboard">
    Explora todos los endpoints de la API de expansión.
  </Card>
</CardGroup>