Skip to main content
GET
/
events
/
user
/
entity
/
{entityId}
/
has-events
Has events by entity
curl --request GET \
  --url http://api.gu1.ai/events/user/entity/{entityId}/has-events \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "hasEvents": true,
  "entityId": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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.

​
Performance

Designed for low latency:
AspectBehavior
QueriesTwo round trips: entity lookup by UUID (PK) + 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/{entityId}/has-events

​
Authentication

Requires a valid API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Path Parameters

​
entityId
string
required
UUID of the entity to check

​
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
Confirmed entity UUID (same as path parameter when the entity exists)

​
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
404ENTITY_NOT_FOUNDEntity UUID does not exist in your organization or is soft-deleted
401—Missing or invalid API key
403—Insufficient permissions (events:read)

​
Examples

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

const entityId = '550e8400-e29b-41d4-a716-446655440000';
const res = await fetch(
  `https://api.gu1.ai/events/user/entity/${entityId}/has-events`,
  { headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { hasEvents } = await res.json();
if (hasEvents) {
  // Load full timeline only when needed
  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