List - gu1

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.

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.

Endpoint

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

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

user_id

string

Filter events by user identifierExample: ?user_id=user_12345

entity_id

string

Filter events by entity UUIDExample: ?entity_id=550e8400-e29b-41d4-a716-446655440000

entity_external_id

string

Filter events by external entity identifierExample: ?entity_external_id=user_12345

tax_id

string

Filter events by tax identification numberExample: ?tax_id=20242455496

event_type

string

Filter events by type (e.g., LOGIN_SUCCESS, TRANSFER_SUCCESS)Example: ?event_type=LOGIN_SUCCESS

start_date

string

Filter events after this date (ISO 8601 format)Example: ?start_date=2026-01-01T00:00:00Z

end_date

string

Filter events before this date (ISO 8601 format)Example: ?end_date=2026-01-31T23:59:59Z

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[].entityExternalId

string

External entity identifier

events[].taxId

string

Tax ID

events[].timestamp

string

Event timestamp (ISO 8601)

events[].deviceId

string

Device identifier

events[].ipAddress

string

IP address

events[].country

string

Country code

events[].isVpn

boolean

VPN detection flag

events[].isProxy

boolean

Proxy detection flag

events[].metadata

object

Event-specific metadata

events[].createdAt

string

Record creation timestamp

pagination

object

Pagination information

pagination.total

number

Total number of events matching the filters

pagination.limit

number

Page size used

pagination.offset

number

Offset used

pagination.hasMore

boolean

Whether there are more pages available

Examples

Basic Query

curl "https://api.gu1.ai/events/user?entity_external_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Event Type

curl "https://api.gu1.ai/events/user?entity_external_id=user_12345&event_type=LOGIN_SUCCESS" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Date Range

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"

Response Example

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

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid date format"
  }
}

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

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "EVENTS_FETCH_FAILED",
    "message": "Failed to fetch events"
  }
}

Use Cases

Audit Trail

Build a complete audit trail for compliance:

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:

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:

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:

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

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

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

Create Event

Track new events

Event Statistics

Get aggregated statistics

List by Entity

Get events for a specific entity

Fraud Detection

Build fraud rules with events

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

​Query Parameters

​Response

​Examples

​Basic Query

​Filter by Event Type

​Filter by Date Range

​Response Example

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​500 Internal Server Error

​Use Cases

​Audit Trail

​Fraud Investigation

​User Timeline

​Filtering Tips

​Multiple Entity Identifiers

​Combining Filters

​Pagination Best Practices

​Iterate Through All Pages

​Next Steps

Create Event

Event Statistics

List by Entity

Fraud Detection

Overview

Endpoint

Authentication

Query Parameters

Response

Examples

Basic Query

Filter by Event Type

Filter by Date Range

Response Example

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

500 Internal Server Error

Use Cases

Audit Trail

Fraud Investigation

User Timeline

Filtering Tips

Multiple Entity Identifiers

Combining Filters

Pagination Best Practices

Iterate Through All Pages

Next Steps