Listar por Entidad

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

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

fetch('http://api.gu1.ai/events/user/entity/{entityId}', 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/entity/{entityId}",
  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/entity/{entityId}"

	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/entity/{entityId}")

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[].timestamp": "<string>",
      "events[].deviceId": "<string>",
      "events[].ipAddress": "<string>",
      "events[].country": "<string>",
      "events[].metadata": {},
      "events[].createdAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  },
  "entity": {
    "entity.id": "<string>",
    "entity.external_id": "<string>",
    "entity.tax_id": "<string>",
    "entity.name": "<string>",
    "entity.type": "<string>"
  }
}

GET

events

user

entity

{entityId}

Listar por Entidad

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

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

fetch('http://api.gu1.ai/events/user/entity/{entityId}', 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/entity/{entityId}",
  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/entity/{entityId}"

	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/entity/{entityId}")

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[].timestamp": "<string>",
      "events[].deviceId": "<string>",
      "events[].ipAddress": "<string>",
      "events[].country": "<string>",
      "events[].metadata": {},
      "events[].createdAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  },
  "entity": {
    "entity.id": "<string>",
    "entity.external_id": "<string>",
    "entity.tax_id": "<string>",
    "entity.name": "<string>",
    "entity.type": "<string>"
  }
}

Resumen

Recupera todos los eventos asociados con una entidad específica, proporcionando una línea de tiempo completa de actividad. Este endpoint busca a través de múltiples identificadores de entidad (entity_id, entity_external_id, tax_id) para asegurar que obtengas todos los eventos relacionados a la entidad independientemente de qué identificador se usó al crear los eventos.

📋 Este endpoint busca automáticamente por ID de entidad, ID externo e ID tributario, así que obtendrás todos los eventos independientemente de qué identificador se usó cuando fueron creados.

Para solo saber si hay eventos (sí/no), usá ¿Tiene eventos? (GET …/has-events) en lugar de listar con limit=1.

Endpoint

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

Autenticación

Requiere una clave API válida en el encabezado de Authorization:

Authorization: Bearer YOUR_API_KEY

Parámetros de Ruta

string

required

UUID de la entidad cuyos eventos deseas recuperar

Parámetros de Consulta

number

default:"100"

Número máximo de eventos a devolver por página (máx: 1000)Ejemplo: ?limit=50

number

default:"0"

Número de eventos a omitir para paginaciónEjemplo: ?offset=100

string

Lista de hasta 100 UUID separados por comas para construir una línea de tiempo combinada. Cada UUID debe corresponder a la entidad del path o a uno de sus relacionados activos dentro de la misma organización.Los eventos se ordenan globalmente por fecha antes de aplicar limit y offset.

Respuesta

boolean

Indica si la solicitud fue exitosa

array

Array de objetos de evento ordenados por timestamp (más reciente primero)

string

UUID del evento

string

Tipo de evento

string

Identificador de usuario

string

UUID de entidad

string

Timestamp del evento (ISO 8601)

string

Identificador del dispositivo

string

Dirección IP

string

Código de país

object

Metadatos específicos del evento

string

Timestamp de creación del registro

object

Información de paginación

number

Número total de eventos para esta entidad

number

Tamaño de página usado

number

Offset usado

boolean

Si hay más páginas disponibles

object

Información de la entidad

string

UUID de entidad

string

Identificador externo de entidad

string

ID tributario

string

Nombre de la entidad

string

Tipo de entidad (person, company, etc.)

Ejemplos

Consulta Básica

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

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

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

Con Paginación

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

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

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

Ejemplo de Respuesta

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

Respuestas de Error

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

Casos de Uso

Registro de Auditoría de Entidad

Genera un registro de auditoría completo para una entidad:

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

Revisión de Cumplimiento

Revisa actividad de entidad para cumplimiento:

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

  // Verifica señales de alerta
  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
  };
}

Visualización de Línea de Tiempo de Entidad

Construye una línea de tiempo para visualización:

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

  // Agrupa eventos por fecha
  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
  };
}

Evaluación de Riesgo

Evalúa riesgo de entidad basado en historial de eventos:

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

  // Verifica inicios de sesión fallidos
  const failedLogins = data.events.filter(e => e.eventType === 'LOGIN_FAILED').length;
  if (failedLogins > 3) {
    riskScore += 20;
    riskFactors.push(`${failedLogins} intentos de inicio de sesión fallidos`);
  }

  // Verifica uso de VPN
  const vpnEvents = data.events.filter(e => e.metadata?.isVpn).length;
  if (vpnEvents > 5) {
    riskScore += 15;
    riskFactors.push(`${vpnEvents} eventos a través de VPN`);
  }

  // Verifica transferencias rápidas
  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} transferencias en las últimas 24 horas`);
  }

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

Mejores Prácticas de Paginación

Cargar Todos los Eventos

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

Próximos Pasos

Crear Evento

Rastrea nuevos eventos

Listar Eventos

Consulta eventos con filtros

Estadísticas de Eventos

Obtén estadísticas agregadas

Análisis de Riesgo

Analiza riesgo de entidad

​Resumen

​Endpoint

​Autenticación

​Parámetros de Ruta

​Parámetros de Consulta

​Respuesta

​Ejemplos

​Consulta Básica

​Con Paginación

​Ejemplo de Respuesta

​Respuestas de Error

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Registro de Auditoría de Entidad

​Revisión de Cumplimiento

​Visualización de Línea de Tiempo de Entidad

​Evaluación de Riesgo

​Mejores Prácticas de Paginación

​Cargar Todos los Eventos

​Próximos Pasos

Crear Evento

Listar Eventos

Estadísticas de Eventos

Análisis de Riesgo

Resumen

Endpoint

Autenticación

Parámetros de Ruta

Parámetros de Consulta

Respuesta

Ejemplos

Consulta Básica

Con Paginación

Ejemplo de Respuesta

Respuestas de Error

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Registro de Auditoría de Entidad

Revisión de Cumplimiento

Visualización de Línea de Tiempo de Entidad

Evaluación de Riesgo

Mejores Prácticas de Paginación

Cargar Todos los Eventos

Próximos Pasos