> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ¿Tiene eventos? (por entidad)

> Comprobación rápida booleana de si una entidad tiene eventos de usuario vinculados — mismo alcance que listar por entidad, sin devolver filas ni totales.

## Descripción general

Usá este endpoint cuando solo necesitás saber **si** una entidad tiene eventos de usuario (badges en UI, visibilidad de pestañas, prechecks), no la línea de tiempo completa. Usa el **mismo criterio de vinculación** que [Listar por entidad](/es/api-reference/events/list-by-entity): `entity_id`, `entity_external_id` o `tax_id` dentro de tu organización.

<Tip>
  Preferí este endpoint frente a listar con `limit=1` cuando solo necesitás sí/no — evita `COUNT(*)`, ordenamiento y serializar payloads de eventos.
</Tip>

<Note>
  **Identificadores de entidad:** podés consultar por query param sin conocer el UUID interno. Prioridad de búsqueda: `entity_id` → `entity_external_id` → `tax_id` (si mandás más de uno, gana el de mayor prioridad). Para `tax_id` la comparación en DB normaliza caracteres no alfanuméricos (p. ej. `20-24245549-6` y `20242455496`).

  La ruta legacy `GET …/entity/{entityId}/has-events` sigue disponible cuando ya tenés el UUID.
</Note>

## Rendimiento

Pensado para baja latencia:

| Aspecto       | Comportamiento                                                                                                                                             |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Consultas** | Dos viajes: lookup de entidad + una sonda `LIMIT 1` en `user_events`                                                                                       |
| **No hace**   | `COUNT(*)`, `ORDER BY`, paginación ni devolver columnas completas de eventos/metadata                                                                      |
| **Índices**   | `organization_id` + `entity_id` usa `idx_user_events_organization_entity_id`; `entity_external_id` y `tax_id` tienen índices dedicados en sus ramas del OR |

La latencia típica la dominan red y autenticación, no escanear historiales grandes.

## Endpoint

```
GET https://api.gu1.ai/events/user/entity/has-events
```

## Autenticación

Requiere API key válida en el header Authorization:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Parámetros de consulta

Al menos **uno** es obligatorio. Si enviás varios, la prioridad es `entity_id` → `entity_external_id` → `tax_id`.

<ParamField query="entity_id" type="string">
  UUID de la entidad (máxima prioridad)

  Ejemplo: `?entity_id=550e8400-e29b-41d4-a716-446655440000`
</ParamField>

<ParamField query="entity_external_id" type="string">
  Identificador externo de la entidad en tu sistema

  Ejemplo: `?entity_external_id=user_12345`
</ParamField>

<ParamField query="tax_id" type="string">
  Documento fiscal (CUIT/CUIL/CPF/CNPJ, etc.). Comparación exacta y normalizada (solo alfanuméricos)

  Ejemplo: `?tax_id=20242455496`
</ParamField>

## Respuesta

<ResponseField name="success" type="boolean">
  Indica si la solicitud fue exitosa
</ResponseField>

<ResponseField name="hasEvents" type="boolean">
  `true` si existe al menos un evento vinculado (mismo alcance que listar por entidad); si no, `false`
</ResponseField>

<ResponseField name="entityId" type="string">
  UUID interno de la entidad resuelta (útil si consultaste por `entity_external_id` o `tax_id`)
</ResponseField>

### Ejemplo — con eventos

```json theme={null}
{
  "success": true,
  "hasEvents": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Ejemplo — sin eventos

```json theme={null}
{
  "success": true,
  "hasEvents": false,
  "entityId": "550e8400-e29b-41d4-a716-446655440000"
}
```

## Errores

| Estado | Código             | Cuándo                                                        |
| ------ | ------------------ | ------------------------------------------------------------- |
| 400    | —                  | Falta cualquier identificador de entidad en query             |
| 404    | `ENTITY_NOT_FOUND` | La entidad no existe en la org o está eliminada (soft delete) |
| 401    | —                  | API key ausente o inválida                                    |
| 403    | —                  | Permisos insuficientes (`events:read`)                        |

## Ejemplos

```bash theme={null}
# Por external ID (caso típico sin UUID interno)
curl "https://api.gu1.ai/events/user/entity/has-events?entity_external_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Por tax ID
curl "https://api.gu1.ai/events/user/entity/has-events?tax_id=20242455496" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Legacy: por UUID en path
curl "https://api.gu1.ai/events/user/entity/550e8400-e29b-41d4-a716-446655440000/has-events" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```javascript theme={null}
const res = await fetch(
  'https://api.gu1.ai/events/user/entity/has-events?entity_external_id=user_12345',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { hasEvents, entityId } = await res.json();
if (hasEvents) {
  const timeline = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}?limit=50`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
}
```

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Listar por entidad" icon="list" href="/es/api-reference/events/list-by-entity">
    Línea de tiempo completa cuando `hasEvents` es true
  </Card>

  <Card title="Listar eventos" icon="filter" href="/es/api-reference/events/list">
    Consultar con filtros
  </Card>

  <Card title="Estadísticas" icon="chart-bar" href="/es/api-reference/events/stats">
    Conteos por tipo de evento
  </Card>

  <Card title="Overview" icon="book" href="/es/api-reference/events/overview">
    Overview de eventos de usuario
  </Card>
</CardGroup>