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

# Listar por Entidad

> Lista todos los eventos de usuario asociados a una entidad específica en la API gu1 — útil para auditorías, depuración de reglas y líneas de tiempo.

## Resumen

Recupera todos los eventos asociados con una entidad específica, proporcionando una línea de tiempo completa de actividad. Este endpoint busca a través de múltiples identificadores de entidad (`entity_id`, `entity_external_id`, `tax_id`) para asegurar que obtengas todos los eventos relacionados a la entidad independientemente de qué identificador se usó al crear los eventos.

<Tip>
  📋 Este endpoint busca automáticamente por ID de entidad, ID externo e ID tributario, así que obtendrás todos los eventos independientemente de qué identificador se usó cuando fueron creados.
</Tip>

<Tip>
  Para solo saber si hay eventos (sí/no), usá [¿Tiene eventos?](/es/api-reference/events/has-events-by-entity) (`GET …/has-events`) en lugar de listar con `limit=1`.
</Tip>

## Endpoint

```
GET https://api.gu1.ai/events/user/entity/{entityId}
```

## Autenticación

Requiere una clave API válida en el encabezado de Authorization:

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

## Parámetros de Ruta

<ParamField path="entityId" type="string" required>
  UUID de la entidad cuyos eventos deseas recuperar
</ParamField>

## Parámetros de Consulta

<ParamField query="limit" type="number" default="100">
  Número máximo de eventos a devolver por página (máx: 1000)

  Ejemplo: `?limit=50`
</ParamField>

<ParamField query="offset" type="number" default="0">
  Número de eventos a omitir para paginación

  Ejemplo: `?offset=100`
</ParamField>

## Respuesta

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

<ResponseField name="events" type="array">
  Array de objetos de evento ordenados por timestamp (más reciente primero)

  <ResponseField name="events[].id" type="string">
    UUID del evento
  </ResponseField>

  <ResponseField name="events[].eventType" type="string">
    Tipo de evento
  </ResponseField>

  <ResponseField name="events[].userId" type="string">
    Identificador de usuario
  </ResponseField>

  <ResponseField name="events[].entityId" type="string">
    UUID de entidad
  </ResponseField>

  <ResponseField name="events[].timestamp" type="string">
    Timestamp del evento (ISO 8601)
  </ResponseField>

  <ResponseField name="events[].deviceId" type="string">
    Identificador del dispositivo
  </ResponseField>

  <ResponseField name="events[].ipAddress" type="string">
    Dirección IP
  </ResponseField>

  <ResponseField name="events[].country" type="string">
    Código de país
  </ResponseField>

  <ResponseField name="events[].metadata" type="object">
    Metadatos específicos del evento
  </ResponseField>

  <ResponseField name="events[].createdAt" type="string">
    Timestamp de creación del registro
  </ResponseField>
</ResponseField>

<ResponseField name="pagination" type="object">
  Información de paginación

  <ResponseField name="pagination.total" type="number">
    Número total de eventos para esta entidad
  </ResponseField>

  <ResponseField name="pagination.limit" type="number">
    Tamaño de página usado
  </ResponseField>

  <ResponseField name="pagination.offset" type="number">
    Offset usado
  </ResponseField>

  <ResponseField name="pagination.hasMore" type="boolean">
    Si hay más páginas disponibles
  </ResponseField>
</ResponseField>

<ResponseField name="entity" type="object">
  Información de la entidad

  <ResponseField name="entity.id" type="string">
    UUID de entidad
  </ResponseField>

  <ResponseField name="entity.external_id" type="string">
    Identificador externo de entidad
  </ResponseField>

  <ResponseField name="entity.tax_id" type="string">
    ID tributario
  </ResponseField>

  <ResponseField name="entity.name" type="string">
    Nombre de la entidad
  </ResponseField>

  <ResponseField name="entity.type" type="string">
    Tipo de entidad (person, company, etc.)
  </ResponseField>
</ResponseField>

## Ejemplos

### Consulta Básica

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.gu1.ai/events/user/entity/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const entityId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(data.events);
  console.log(data.entity);
  ```

  ```python Python theme={null}
  import requests

  entity_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.get(
      f'https://api.gu1.ai/events/user/entity/{entity_id}',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  data = response.json()
  print(data['events'])
  print(data['entity'])
  ```
</CodeGroup>

### Con Paginación

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.gu1.ai/events/user/entity/550e8400-e29b-41d4-a716-446655440000?limit=50&offset=0" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const entityId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}?limit=50&offset=0`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();
  console.log(`Page 1 of ${Math.ceil(data.pagination.total / 50)} pages`);
  ```

  ```python Python theme={null}
  import requests

  entity_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.get(
      f'https://api.gu1.ai/events/user/entity/{entity_id}',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'limit': 50, 'offset': 0}
  )

  data = response.json()
  print(f"Page 1 of {data['pagination']['total'] // 50 + 1} pages")
  ```
</CodeGroup>

## Ejemplo de Respuesta

```json theme={null}
{
  "success": true,
  "events": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "eventType": "LOGIN_SUCCESS",
      "userId": "user_12345",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2026-01-30T14:30:00Z",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "metadata": {},
      "createdAt": "2026-01-30T14:30:00Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "eventType": "TRANSFER_SUCCESS",
      "userId": "user_12345",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2026-01-30T12:15:00Z",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "metadata": {
        "amount": 5000,
        "currency": "ARS"
      },
      "createdAt": "2026-01-30T12:15:00Z"
    }
  ],
  "pagination": {
    "total": 145,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  },
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "user_12345",
    "tax_id": "20242455496",
    "name": "John Doe",
    "type": "person"
  }
}
```

## Respuestas de Error

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}
```

### 403 Forbidden

```json theme={null}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to read events"
  }
}
```

### 404 Not Found

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}
```

### 500 Internal Server Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "EVENTS_FETCH_FAILED",
    "message": "Failed to fetch entity events"
  }
}
```

## Casos de Uso

### Registro de Auditoría de Entidad

Genera un registro de auditoría completo para una entidad:

```javascript theme={null}
async function getEntityAuditTrail(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}?limit=1000`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  const auditTrail = {
    entity: data.entity,
    totalEvents: data.pagination.total,
    events: data.events.map(event => ({
      timestamp: event.timestamp,
      action: event.eventType,
      device: event.deviceId,
      location: `${event.ipAddress} (${event.country})`,
      metadata: event.metadata
    }))
  };

  return auditTrail;
}
```

### Revisión de Cumplimiento

Revisa actividad de entidad para cumplimiento:

```javascript theme={null}
async function complianceReview(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Verifica señales de alerta
  const loginAttempts = data.events.filter(e => e.eventType === 'LOGIN_FAILED');
  const transfers = data.events.filter(e => e.eventType === 'TRANSFER_SUCCESS');
  const credentialChanges = data.events.filter(e =>
    ['PASSWORD_CHANGE', 'EMAIL_CHANGE', 'PHONE_CHANGE'].includes(e.eventType)
  );

  return {
    entityInfo: data.entity,
    redFlags: {
      failedLogins: loginAttempts.length,
      totalTransfers: transfers.length,
      credentialChanges: credentialChanges.length
    },
    requiresReview: loginAttempts.length > 5 || credentialChanges.length > 3
  };
}
```

### Visualización de Línea de Tiempo de Entidad

Construye una línea de tiempo para visualización:

```javascript theme={null}
async function buildEntityTimeline(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Agrupa eventos por fecha
  const timeline = data.events.reduce((acc, event) => {
    const date = event.timestamp.split('T')[0];
    if (!acc[date]) {
      acc[date] = [];
    }
    acc[date].push({
      time: event.timestamp,
      type: event.eventType,
      details: event.metadata
    });
    return acc;
  }, {});

  return {
    entity: data.entity,
    timeline
  };
}
```

### Evaluación de Riesgo

Evalúa riesgo de entidad basado en historial de eventos:

```javascript theme={null}
async function assessEntityRisk(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  let riskScore = 0;
  const riskFactors = [];

  // Verifica inicios de sesión fallidos
  const failedLogins = data.events.filter(e => e.eventType === 'LOGIN_FAILED').length;
  if (failedLogins > 3) {
    riskScore += 20;
    riskFactors.push(`${failedLogins} intentos de inicio de sesión fallidos`);
  }

  // Verifica uso de VPN
  const vpnEvents = data.events.filter(e => e.metadata?.isVpn).length;
  if (vpnEvents > 5) {
    riskScore += 15;
    riskFactors.push(`${vpnEvents} eventos a través de VPN`);
  }

  // Verifica transferencias rápidas
  const transfers = data.events.filter(e => e.eventType === 'TRANSFER_SUCCESS');
  const recentTransfers = transfers.filter(e =>
    new Date(e.timestamp) > new Date(Date.now() - 86400000)
  );
  if (recentTransfers.length > 5) {
    riskScore += 25;
    riskFactors.push(`${recentTransfers.length} transferencias en las últimas 24 horas`);
  }

  return {
    entity: data.entity,
    riskScore: Math.min(riskScore, 100),
    riskLevel: riskScore > 50 ? 'HIGH' : riskScore > 25 ? 'MEDIUM' : 'LOW',
    riskFactors
  };
}
```

## Mejores Prácticas de Paginación

### Cargar Todos los Eventos

```javascript theme={null}
async function getAllEntityEvents(entityId) {
  const allEvents = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.gu1.ai/events/user/entity/${entityId}?limit=${limit}&offset=${offset}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );

    const data = await response.json();
    allEvents.push(...data.events);

    hasMore = data.pagination.hasMore;
    offset += limit;
  }

  return {
    entity: data.entity,
    events: allEvents
  };
}
```

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Crear Evento" icon="plus" href="/es/api-reference/events/create">
    Rastrea nuevos eventos
  </Card>

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

  <Card title="Estadísticas de Eventos" icon="chart-bar" href="/es/api-reference/events/stats">
    Obtén estadísticas agregadas
  </Card>

  <Card title="Análisis de Riesgo" icon="shield-check" href="/es/use-cases/transaction-monitoring/overview">
    Analiza riesgo de entidad
  </Card>
</CardGroup>