List by Entity

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.

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

Endpoint

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

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Path Parameters

entityId

string

required

UUID of the entity whose events you want to retrieve

Query Parameters

limit

number

default:"100"

Maximum number of events to return per page (max: 1000)Example: ?limit=50

offset

number

default:"0"

Number of events to skip for paginationExample: ?offset=100

Response

success

boolean

Indicates if the request was successful

events

array

Array of event objects sorted by timestamp (newest first)

events[].id

string

Event UUID

events[].eventType

string

Type of event

events[].userId

string

User identifier

events[].entityId

string

Entity UUID

events[].timestamp

string

Event timestamp (ISO 8601)

events[].deviceId

string

Device identifier

events[].ipAddress

string

IP address

events[].country

string

Country code

events[].metadata

object

Event-specific metadata

events[].createdAt

string

Record creation timestamp

pagination

object

Pagination information

pagination.total

number

Total number of events for this entity

pagination.limit

number

Page size used

pagination.offset

number

Offset used

pagination.hasMore

boolean

Whether there are more pages available

entity

object

Entity information

entity.id

string

Entity UUID

entity.external_id

string

External entity identifier

entity.tax_id

string

Tax ID

entity.name

string

Entity name

entity.type

string

Entity type (person, company, etc.)

Examples

Basic Query

curl https://api.gu1.ai/events/user/entity/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

With Pagination

curl "https://api.gu1.ai/events/user/entity/550e8400-e29b-41d4-a716-446655440000?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

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

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to read events"
  }
}

404 Not Found

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

500 Internal Server Error

{
  "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:

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:

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:

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:

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

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

Create Event

Track new events

List Events

Query events with filters

Event Statistics

Get aggregated statistics

Risk Analysis

Analyze entity risk

Getting Started

Use Cases

Webhooks

Person

Company

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Overview

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Response

​Examples

​Basic Query

​With Pagination

​Response Example

​Error Responses

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Use Cases

​Entity Audit Trail

​Compliance Review

​Entity Timeline Visualization

​Risk Assessment

​Pagination Best Practices

​Load All Events

​Next Steps

Create Event

List Events

Event Statistics

Risk Analysis

Overview

Endpoint

Authentication

Path Parameters

Query Parameters

Response

Examples

Basic Query

With Pagination

Response Example

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Use Cases

Entity Audit Trail

Compliance Review

Entity Timeline Visualization

Risk Assessment

Pagination Best Practices

Load All Events

Next Steps