> ## 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 eventos de usuario

> Consulta eventos de usuario con filtros avanzados — para seguimiento de comportamiento de usuarios y detección de fraude en gu1, con ejemplos para list.

## Resumen

Recupera eventos de usuario con potentes capacidades de filtrado. Usa este endpoint para consultar eventos por usuario, entidad, tipo de evento, rango de fechas y más. Perfecto para construir registros de auditoría, herramientas de investigación de fraude y dashboards de análisis.

<Note>
  **Lógica OR para IDs de Entidad**: Al consultar por identificadores de entidad (`entity_id`, `entity_external_id`, `tax_id`), el sistema usa lógica OR, devolviendo eventos que coincidan con cualquiera de los identificadores proporcionados.
</Note>

## Endpoint

```
GET https://api.gu1.ai/events/user
```

## Autenticación

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

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

## Parámetros de Consulta

<ParamField query="user_id" type="string">
  Filtra eventos por identificador de usuario

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

<ParamField query="entity_id" type="string">
  Filtra eventos por UUID de entidad

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

<ParamField query="entity_external_id" type="string">
  Filtra eventos por identificador externo de entidad

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

<ParamField query="tax_id" type="string">
  Filtra eventos por número de identificación tributaria

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

<ParamField query="event_type" type="string">
  Filtra eventos por tipo (ej., LOGIN\_SUCCESS, TRANSFER\_SUCCESS)

  Ejemplo: `?event_type=LOGIN_SUCCESS`
</ParamField>

<ParamField query="start_date" type="string">
  Filtra eventos después de esta fecha (formato ISO 8601)

  Ejemplo: `?start_date=2026-01-01T00:00:00Z`
</ParamField>

<ParamField query="end_date" type="string">
  Filtra eventos antes de esta fecha (formato ISO 8601)

  Ejemplo: `?end_date=2026-01-31T23:59:59Z`
</ParamField>

<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[].entityExternalId" type="string">
    Identificador externo de entidad
  </ResponseField>

  <ResponseField name="events[].taxId" type="string">
    ID tributario
  </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[].isVpn" type="boolean">
    Bandera de detección de VPN
  </ResponseField>

  <ResponseField name="events[].isProxy" type="boolean">
    Bandera de detección de proxy
  </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 que coinciden con los filtros
  </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>

## Ejemplos

### Consulta Básica

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.gu1.ai/events/user?entity_external_id=user_12345" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.gu1.ai/events/user?entity_external_id=user_12345',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

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

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

  response = requests.get(
      'https://api.gu1.ai/events/user',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'entity_external_id': 'user_12345'}
  )

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

### Filtrar por Tipo de Evento

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.gu1.ai/events/user?entity_external_id=user_12345&event_type=LOGIN_SUCCESS" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.gu1.ai/events/user?entity_external_id=user_12345&event_type=LOGIN_SUCCESS',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  ```

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

  response = requests.get(
      'https://api.gu1.ai/events/user',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'entity_external_id': 'user_12345',
          'event_type': 'LOGIN_SUCCESS'
      }
  )
  ```
</CodeGroup>

### Filtrar por Rango de Fechas

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.gu1.ai/events/user?entity_external_id=user_12345&start_date=2026-01-01T00:00:00Z&end_date=2026-01-31T23:59:59Z" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const startDate = new Date('2026-01-01').toISOString();
  const endDate = new Date('2026-01-31').toISOString();

  const response = await fetch(
    `https://api.gu1.ai/events/user?entity_external_id=user_12345&start_date=${startDate}&end_date=${endDate}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  ```

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

  start_date = datetime(2026, 1, 1).isoformat() + 'Z'
  end_date = datetime(2026, 1, 31, 23, 59, 59).isoformat() + 'Z'

  response = requests.get(
      'https://api.gu1.ai/events/user',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={
          'entity_external_id': 'user_12345',
          'start_date': start_date,
          'end_date': end_date
      }
  )
  ```
</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",
      "entityExternalId": "user_12345",
      "taxId": "20242455496",
      "timestamp": "2026-01-30T14:30:00Z",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "isVpn": false,
      "isProxy": false,
      "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",
      "entityExternalId": "user_12345",
      "taxId": "20242455496",
      "timestamp": "2026-01-30T12:15:00Z",
      "deviceId": "840e89e4d46efd67",
      "ipAddress": "10.40.64.231",
      "country": "AR",
      "metadata": {
        "amount": 5000,
        "currency": "ARS",
        "destinationAccountId": "0170042640000004234411"
      },
      "createdAt": "2026-01-30T12:15:00Z"
    }
  ],
  "pagination": {
    "total": 145,
    "limit": 100,
    "offset": 0,
    "hasMore": true
  }
}
```

## Respuestas de Error

### 400 Bad Request

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid date format"
  }
}
```

### 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"
  }
}
```

### 500 Internal Server Error

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

## Casos de Uso

### Registro de Auditoría

Construye un registro de auditoría completo para cumplimiento:

```javascript theme={null}
async function getAuditTrail(entityExternalId, startDate, endDate) {
  const response = await fetch(
    `https://api.gu1.ai/events/user?` +
    `entity_external_id=${entityExternalId}&` +
    `start_date=${startDate}&` +
    `end_date=${endDate}&` +
    `limit=1000`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();
  return data.events.map(event => ({
    timestamp: event.timestamp,
    action: event.eventType,
    user: event.userId,
    device: event.deviceId,
    ipAddress: event.ipAddress
  }));
}
```

### Investigación de Fraude

Investiga actividad sospechosa:

```javascript theme={null}
async function investigateSuspiciousActivity(entityExternalId) {
  // Obtiene inicios de sesión fallidos recientes
  const failedLogins = await fetch(
    `https://api.gu1.ai/events/user?` +
    `entity_external_id=${entityExternalId}&` +
    `event_type=LOGIN_FAILED&` +
    `start_date=${new Date(Date.now() - 86400000).toISOString()}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );

  // Obtiene transferencias recientes
  const transfers = await fetch(
    `https://api.gu1.ai/events/user?` +
    `entity_external_id=${entityExternalId}&` +
    `event_type=TRANSFER_SUCCESS&` +
    `start_date=${new Date(Date.now() - 86400000).toISOString()}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  );

  return {
    failedLogins: (await failedLogins.json()).events,
    transfers: (await transfers.json()).events
  };
}
```

### Línea de Tiempo de Usuario

Construye una línea de tiempo de actividad de usuario:

```javascript theme={null}
async function getUserTimeline(userId, limit = 50) {
  const response = await fetch(
    `https://api.gu1.ai/events/user?user_id=${userId}&limit=${limit}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();
  return data.events;
}
```

## Consejos de Filtrado

### Múltiples Identificadores de Entidad

Puedes proporcionar múltiples identificadores de entidad para ampliar la búsqueda:

```javascript theme={null}
// Devolverá eventos que coincidan con CUALQUIERA de estos identificadores
const response = await fetch(
  `https://api.gu1.ai/events/user?` +
  `entity_external_id=user_12345&` +
  `tax_id=20242455496`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
```

### Combinando Filtros

Combina múltiples filtros para consultas precisas:

```javascript theme={null}
// Obtiene transferencias fallidas en la última semana
const lastWeek = new Date(Date.now() - 7 * 86400000).toISOString();

const response = await fetch(
  `https://api.gu1.ai/events/user?` +
  `entity_external_id=user_12345&` +
  `event_type=TRANSFER_FAILED&` +
  `start_date=${lastWeek}`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
```

## Mejores Prácticas de Paginación

### Iterar a Través de Todas las Páginas

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

  while (hasMore) {
    const response = await fetch(
      `https://api.gu1.ai/events/user?` +
      `entity_external_id=${entityExternalId}&` +
      `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 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="Estadísticas de Eventos" icon="chart-bar" href="/es/api-reference/events/stats">
    Obtén estadísticas agregadas
  </Card>

  <Card title="Listar por Entidad" icon="user" href="/es/api-reference/events/list-by-entity">
    Obtén eventos para una entidad específica
  </Card>

  <Card title="Detección de Fraude" icon="shield-check" href="/es/use-cases/transaction-monitoring/fraud-detection">
    Construye reglas de fraude con eventos
  </Card>
</CardGroup>