Listar por Entidade

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 Entidade

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

Visão Geral

Recupera todos os eventos associados a uma entidade específica, fornecendo uma linha do tempo completa de atividades. Este endpoint pesquisa entre múltiplos identificadores de entidade (entity_id, entity_external_id, tax_id) para garantir que você obtenha todos os eventos relacionados à entidade, independentemente de qual identificador foi usado ao criar os eventos.

📋 Este endpoint pesquisa automaticamente por ID de entidade, ID externo e ID fiscal, então você obterá todos os eventos independentemente de qual identificador foi usado quando foram criados.

Para apenas saber se há eventos (sim/não), use Tem eventos? (GET …/has-events) em vez de listar com limit=1.

Endpoint

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

Autenticação

Requer uma chave de API válida no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Parâmetros de Caminho

string

required

UUID da entidade cujos eventos você deseja recuperar

Parâmetros de Consulta

number

default:"100"

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

number

default:"0"

Número de eventos a pular para paginaçãoExemplo: ?offset=100

string

Lista de até 100 UUIDs separados por vírgulas para montar uma linha do tempo combinada. Cada UUID deve identificar a entidade do path ou uma de suas entidades relacionadas ativas na mesma organização.Os eventos são ordenados globalmente por data antes da aplicação de limit e offset.

Resposta

boolean

Indica se a requisição foi bem-sucedida

array

Array de objetos de eventos ordenados por timestamp (mais recente primeiro)

string

UUID do evento

string

Tipo de evento

string

Identificador do usuário

string

UUID da entidade

string

Timestamp do evento (ISO 8601)

string

Identificador do dispositivo

string

Endereço IP

string

Código do país

object

Metadados específicos do evento

string

Timestamp de criação do registro

object

Informações de paginação

number

Número total de eventos para esta entidade

number

Tamanho de página usado

number

Offset usado

boolean

Se há mais páginas disponíveis

object

Informações da entidade

string

UUID da entidade

string

Identificador externo da entidade

string

ID fiscal

string

Nome da entidade

string

Tipo de entidade (person, company, etc.)

Exemplos

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

Com Paginação

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

Exemplo de Resposta

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

Respostas de Erro

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

Trilha de Auditoria da Entidade

Gerar uma trilha de auditoria completa para uma entidade:

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

Revisão de Conformidade

Revisar atividade da entidade para conformidade:

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

  // Verificar bandeiras vermelhas
  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
  };
}

Visualização da Linha do Tempo da Entidade

Construir uma linha do tempo para visualização:

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

  // Agrupar eventos por data
  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
  };
}

Avaliação de Risco

Avaliar risco da entidade baseado no histórico 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 = [];

  // Verificar logins falhos
  const failedLogins = data.events.filter(e => e.eventType === 'LOGIN_FAILED').length;
  if (failedLogins > 3) {
    riskScore += 20;
    riskFactors.push(`${failedLogins} tentativas de login falhas`);
  }

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

  // Verificar transferências 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} transferências nas últimas 24 horas`);
  }

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

Melhores Práticas de Paginação

Carregar Todos os 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 Passos

Criar Evento

Rastrear novos eventos

Listar Eventos

Consultar eventos com filtros

Estatísticas de Eventos

Obter estatísticas agregadas

Análise de Risco

Analisar risco da entidade

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Caminho

​Parâmetros de Consulta

​Resposta

​Exemplos

​Consulta Básica

​Com Paginação

​Exemplo de Resposta

​Respostas de Erro

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Trilha de Auditoria da Entidade

​Revisão de Conformidade

​Visualização da Linha do Tempo da Entidade

​Avaliação de Risco

​Melhores Práticas de Paginação

​Carregar Todos os Eventos

​Próximos Passos

Criar Evento

Listar Eventos

Estatísticas de Eventos

Análise de Risco

Visão Geral

Endpoint

Autenticação

Parâmetros de Caminho

Parâmetros de Consulta

Resposta

Exemplos

Consulta Básica

Com Paginação

Exemplo de Resposta

Respostas de Erro

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Trilha de Auditoria da Entidade

Revisão de Conformidade

Visualização da Linha do Tempo da Entidade

Avaliação de Risco

Melhores Práticas de Paginação

Carregar Todos os Eventos

Próximos Passos