Has events by entity
curl --request GET \
--url http://api.gu1.ai/events/user/entity/has-events \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/events/user/entity/has-events"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)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))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/events/user/entity/has-events")
.header("Authorization", "Bearer <token>")
.asString();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>"
}API Reference
Has events by entity
Fast boolean check whether an entity has any linked user events β same linkage scope as list-by-entity without returning event rows or counts.
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>'import requests
url = "http://api.gu1.ai/events/user/entity/has-events"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)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))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/events/user/entity/has-events")
.header("Authorization", "Bearer <token>")
.asString();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 |
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 isentity_id β entity_external_id β tax_id.
string
Entity UUID (highest priority)Example:
?entity_id=550e8400-e29b-41d4-a716-446655440000string
Your external entity identifierExample:
?entity_external_id=user_12345string
Tax ID (CUIT/CUIL/CPF/CNPJ, etc.). Exact and normalized match (alphanumeric only)Example:
?tax_id=20242455496Response
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 falsestring
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 trueList Events
Query events with filters
Event Statistics
Aggregated counts by event type
Events Overview
User events API overview
Was this page helpful?