> ## 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 by Entity

> Get all events for a specific entity — for user behavior tracking and rule-based fraud detection in gu1, with examples for list by entity use cases.

## Overview

Retrieves all events associated with a specific entity, providing a complete activity timeline. This endpoint searches across multiple entity identifiers (`entity_id`, `entity_external_id`, `tax_id`) to ensure you get all events related to the entity regardless of which identifier was used when creating the events.

<Tip>
  📋 This endpoint automatically searches by entity ID, external ID, and tax ID, so you'll get all events regardless of which identifier was used when they were created.
</Tip>

<Tip>
  For a fast yes/no check only, use [Has events by entity](/en/api-reference/events/has-events-by-entity) (`GET …/has-events`) instead of listing with `limit=1`.
</Tip>

## Endpoint

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

## Authentication

Requires a valid API key in the Authorization header:

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

## Path Parameters

<ParamField path="entityId" type="string" required>
  UUID of the entity whose events you want to retrieve
</ParamField>

## Query Parameters

<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[].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[].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 for this entity
  </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>

<ResponseField name="entity" type="object">
  Entity information

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

  <ResponseField name="entity.external_id" type="string">
    External entity identifier
  </ResponseField>

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

  <ResponseField name="entity.name" type="string">
    Entity name
  </ResponseField>

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

## Examples

### Basic Query

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

### With Pagination

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

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

## Error Responses

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

## Use Cases

### Entity Audit Trail

Generate a complete audit trail for an entity:

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

### Compliance Review

Review entity activity for compliance:

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

  // Check for red flags
  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
  };
}
```

### Entity Timeline Visualization

Build a timeline for visualization:

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

  // Group events by date
  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
  };
}
```

### Risk Assessment

Assess entity risk based on event history:

```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 = [];

  // Check failed logins
  const failedLogins = data.events.filter(e => e.eventType === 'LOGIN_FAILED').length;
  if (failedLogins > 3) {
    riskScore += 20;
    riskFactors.push(`${failedLogins} failed login attempts`);
  }

  // Check VPN usage
  const vpnEvents = data.events.filter(e => e.metadata?.isVpn).length;
  if (vpnEvents > 5) {
    riskScore += 15;
    riskFactors.push(`${vpnEvents} events through VPN`);
  }

  // Check rapid transfers
  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} transfers in last 24 hours`);
  }

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

## Pagination Best Practices

### Load All Events

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

## Next Steps

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

  <Card title="List Events" icon="list" href="/en/api-reference/events/list">
    Query events with filters
  </Card>

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

  <Card title="Risk Analysis" icon="shield-check" href="/en/use-cases/transaction-monitoring/overview">
    Analyze entity risk
  </Card>
</CardGroup>