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

# List user events

> Query user events with advanced filters — for user behavior tracking and rule-based fraud detection in gu1, with examples for list use cases.

## Overview

Retrieves user events with powerful filtering capabilities. Use this endpoint to query events by user, entity, event type, date range, and more. Perfect for building audit trails, fraud investigation tools, and analytics dashboards.

<Note>
  **OR Logic for Entity IDs**: When querying by entity identifiers (`entity_id`, `entity_external_id`, `tax_id`), the system uses OR logic, returning events that match any of the provided identifiers.
</Note>

## Endpoint

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

## Authentication

Requires a valid API key in the Authorization header:

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

## Query Parameters

<ParamField query="user_id" type="string">
  Filter events by user identifier

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

<ParamField query="entity_id" type="string">
  Filter events by entity UUID

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

<ParamField query="entity_external_id" type="string">
  Filter events by external entity identifier

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

<ParamField query="tax_id" type="string">
  Filter events by tax identification number

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

<ParamField query="event_type" type="string">
  Filter events by type (e.g., LOGIN\_SUCCESS, TRANSFER\_SUCCESS)

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

<ParamField query="start_date" type="string">
  Filter events after this date (ISO 8601 format)

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

<ParamField query="end_date" type="string">
  Filter events before this date (ISO 8601 format)

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

<ParamField query="limit" type="number" default="100">
  Maximum number of events to return per page (max: 1000)

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

<ParamField query="offset" type="number" default="0">
  Number of events to skip for pagination

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

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="events" type="array">
  Array of event objects sorted by timestamp (newest first)

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

  <ResponseField name="events[].eventType" type="string">
    Type of event
  </ResponseField>

  <ResponseField name="events[].userId" type="string">
    User identifier
  </ResponseField>

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

  <ResponseField name="events[].entityExternalId" type="string">
    External entity identifier
  </ResponseField>

  <ResponseField name="events[].taxId" type="string">
    Tax ID
  </ResponseField>

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

  <ResponseField name="events[].deviceId" type="string">
    Device identifier
  </ResponseField>

  <ResponseField name="events[].ipAddress" type="string">
    IP address
  </ResponseField>

  <ResponseField name="events[].country" type="string">
    Country code
  </ResponseField>

  <ResponseField name="events[].isVpn" type="boolean">
    VPN detection flag
  </ResponseField>

  <ResponseField name="events[].isProxy" type="boolean">
    Proxy detection flag
  </ResponseField>

  <ResponseField name="events[].metadata" type="object">
    Event-specific metadata
  </ResponseField>

  <ResponseField name="events[].createdAt" type="string">
    Record creation timestamp
  </ResponseField>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination information

  <ResponseField name="pagination.total" type="number">
    Total number of events matching the filters
  </ResponseField>

  <ResponseField name="pagination.limit" type="number">
    Page size used
  </ResponseField>

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

  <ResponseField name="pagination.hasMore" type="boolean">
    Whether there are more pages available
  </ResponseField>
</ResponseField>

## Examples

### Basic Query

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

### Filter by Event Type

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

### Filter by Date Range

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

## Response Example

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

## Error Responses

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

## Use Cases

### Audit Trail

Build a complete audit trail for compliance:

```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
  }));
}
```

### Fraud Investigation

Investigate suspicious activity:

```javascript theme={null}
async function investigateSuspiciousActivity(entityExternalId) {
  // Get recent failed logins
  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}` } }
  );

  // Get recent transfers
  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
  };
}
```

### User Timeline

Build a user activity timeline:

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

## Filtering Tips

### Multiple Entity Identifiers

You can provide multiple entity identifiers to cast a wider net:

```javascript theme={null}
// Will return events matching ANY of these identifiers
const response = await fetch(
  `https://api.gu1.ai/events/user?` +
  `entity_external_id=user_12345&` +
  `tax_id=20242455496`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
```

### Combining Filters

Combine multiple filters for precise queries:

```javascript theme={null}
// Get failed transfers in the last week
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}` } }
);
```

## Pagination Best Practices

### Iterate Through All Pages

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Event" icon="plus" href="/en/api-reference/events/create">
    Track new events
  </Card>

  <Card title="Event Statistics" icon="chart-bar" href="/en/api-reference/events/stats">
    Get aggregated statistics
  </Card>

  <Card title="List by Entity" icon="user" href="/en/api-reference/events/list-by-entity">
    Get events for a specific entity
  </Card>

  <Card title="Fraud Detection" icon="shield-check" href="/en/use-cases/transaction-monitoring/fraud-detection">
    Build fraud rules with events
  </Card>
</CardGroup>