List user events

List

curl --request GET \
  --url http://api.gu1.ai/events/user \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/events/user', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/events/user",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/events/user"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/events/user")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "events": [
    {
      "events[].id": "<string>",
      "events[].eventType": "<string>",
      "events[].userId": "<string>",
      "events[].entityId": "<string>",
      "events[].entityExternalId": "<string>",
      "events[].taxId": "<string>",
      "events[].timestamp": "<string>",
      "events[].deviceId": "<string>",
      "events[].ipAddress": "<string>",
      "events[].country": "<string>",
      "events[].isVpn": true,
      "events[].isProxy": true,
      "events[].metadata": {},
      "events[].createdAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  }
}

GET

events

user

List

curl --request GET \
  --url http://api.gu1.ai/events/user \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/events/user', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/events/user",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/events/user"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/events/user")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "events": [
    {
      "events[].id": "<string>",
      "events[].eventType": "<string>",
      "events[].userId": "<string>",
      "events[].entityId": "<string>",
      "events[].entityExternalId": "<string>",
      "events[].taxId": "<string>",
      "events[].timestamp": "<string>",
      "events[].deviceId": "<string>",
      "events[].ipAddress": "<string>",
      "events[].country": "<string>",
      "events[].isVpn": true,
      "events[].isProxy": true,
      "events[].metadata": {},
      "events[].createdAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  }
}

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

string

Filter events by user identifierExample: ?user_id=user_12345

string

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

string

Filter events by external entity identifierExample: ?entity_external_id=user_12345

string

Filter events by tax identification numberExample: ?tax_id=20242455496

string

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

string

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

string

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

number

default:"100"

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

number

default:"0"

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

Response

boolean

Indicates if the request was successful

array

Array of event objects sorted by timestamp (newest first)

string

Event UUID

string

Type of event

string

User identifier

string

Entity UUID

string

External entity identifier

string

Tax ID

string

Event timestamp (ISO 8601)

string

Device identifier

string

IP address

string

Country code

boolean

VPN detection flag

boolean

Proxy detection flag

object

Event-specific metadata

string

Record creation timestamp

object

Pagination information

number

Total number of events matching the filters

number

Page size used

number

Offset used

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"

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

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'])

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"

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

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'
    }
)

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"

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

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

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

​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