Skip to main content
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>'
{
  "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:
AspectBehavior
QueriesTwo round trips: entity lookup + one LIMIT 1 probe on user_events
NoCOUNT(*), ORDER BY, pagination, or full event / metadata columns in the response
Indexesorganization_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.
​
entity_id
string
Entity UUID (highest priority)Example: ?entity_id=550e8400-e29b-41d4-a716-446655440000
​
entity_external_id
string
Your external entity identifierExample: ?entity_external_id=user_12345
​
tax_id
string
Tax ID (CUIT/CUIL/CPF/CNPJ, etc.). Exact and normalized match (alphanumeric only)Example: ?tax_id=20242455496

​
Response

​
success
boolean
Indicates if the request was successful
​
hasEvents
boolean
true if at least one user event is linked to this entity (same scope as list-by-entity); otherwise false
​
entityId
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

StatusCodeWhen
400—No entity identifier provided in query
404ENTITY_NOT_FOUNDEntity 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