Has events by entity

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

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

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

	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/has-events")

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,
  "hasEvents": true,
  "entityId": "<string>"
}

GET

events

user

entity

has-events

Has events by entity

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

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

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

	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/has-events")

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,
  "hasEvents": true,
  "entityId": "<string>"
}

Overview

Use this endpoint when you only need to know if an entity has user events (for UI badges, tab visibility, or preflight checks), not the full timeline. It uses the same matching scope as List by Entity: entity_id, entity_external_id, or tax_id within your organization.

Prefer this endpoint over listing events with limit=1 when you only need a yes/no answer — it avoids COUNT(*), sorting, and serializing event payloads.

Entity identifiers: you can query by query parameter without the internal UUID. Lookup priority: entity_id → entity_external_id → tax_id (when multiple are sent, the highest-priority wins). For tax_id, the DB comparison normalizes non-alphanumeric characters (e.g. 20-24245549-6 and 20242455496).The legacy route GET …/entity/{entityId}/has-events remains available when you already have the UUID.

Performance

Designed for low latency:

Aspect	Behavior
Queries	Two round trips: entity lookup + one `LIMIT 1` probe on `user_events`
No	`COUNT(*)`, `ORDER BY`, pagination, or full event / metadata columns in the response
Indexes	`organization_id` + `entity_id` uses `idx_user_events_organization_entity_id`; `entity_external_id` and `tax_id` use dedicated indexes when the OR branch matches those identifiers

Typical latency is dominated by network and auth, not by scanning large event histories.

Endpoint

GET https://api.gu1.ai/events/user/entity/has-events

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Query Parameters

At least one is required. If you send multiple, priority is entity_id → entity_external_id → tax_id.

string

Entity UUID (highest priority)Example: ?entity_id=550e8400-e29b-41d4-a716-446655440000

string

Your external entity identifierExample: ?entity_external_id=user_12345

string

Tax ID (CUIT/CUIL/CPF/CNPJ, etc.). Exact and normalized match (alphanumeric only)Example: ?tax_id=20242455496

Response

boolean

Indicates if the request was successful

boolean

true if at least one user event is linked to this entity (same scope as list-by-entity); otherwise false

string

Resolved internal entity UUID (useful when you queried by entity_external_id or tax_id)

Example — has events

{
  "success": true,
  "hasEvents": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000"
}

Example — no events

{
  "success": true,
  "hasEvents": false,
  "entityId": "550e8400-e29b-41d4-a716-446655440000"
}

Errors

Status	Code	When
400	—	No entity identifier provided in query
404	`ENTITY_NOT_FOUND`	Entity does not exist in your organization or is soft-deleted
401	—	Missing or invalid API key
403	—	Insufficient permissions (`events:read`)

Examples

# By external ID (typical when you don't have the internal UUID)
curl "https://api.gu1.ai/events/user/entity/has-events?entity_external_id=user_12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

# By tax ID
curl "https://api.gu1.ai/events/user/entity/has-events?tax_id=20242455496" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

const res = await fetch(
  'https://api.gu1.ai/events/user/entity/has-events?entity_external_id=user_12345',
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { hasEvents, entityId } = await res.json();
if (hasEvents) {
  const timeline = await fetch(
    `https://api.gu1.ai/events/user/entity/${entityId}?limit=50`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
}

Next Steps

List by Entity

Full event timeline when hasEvents is true

List Events

Query events with filters

Event Statistics

Aggregated counts by event type

Events Overview

User events API overview

⌘I

​Overview

​Performance

​Endpoint

​Authentication

​Query Parameters

​Response

​Example — has events

​Example — no events

​Errors

​Examples

​Next Steps

List by Entity

List Events

Event Statistics

Events Overview

Overview

Performance

Endpoint

Authentication

Query Parameters

Response

Example — has events

Example — no events

Errors

Examples

Next Steps