Events API
Send typed events from servers, workers, or custom clients.
Last updated June 3, 2026
Use POST /api/v1/events for trusted backend events. Send an application identity in userId; send visitorId only when you have an opaque Grometrics visitor ID. If both are present, Grometrics binds or merges them before storing the event. Grometrics does not treat the calling server's IP address as visitor location evidence; include country or region only when those values describe the visitor rather than the calling server. For retryable events, send the event's own stable eventId; Grometrics automatically creates the internal deduplication key.
Workspace-scoped authentication
Send a workspace API key as a Bearer token and include websiteId. Grometrics verifies that the site or tracked app belongs to that workspace before accepting the request.
Replace YOUR_SITE_ID with your site ID from Settings > Tracking.
POST /api/v1/events
1curl https://usegrometrics.com/api/v1/events \2-H "Authorization: Bearer YOUR_API_KEY" \3-H "Content-Type: application/json" \4-d '{5"websiteId": "YOUR_SITE_ID",6"userId": "user_123",7"externalSessionId": "app_session_456",8"event": "project_created",9"eventId": "project_456",10"properties": { "plan": "pro" }11}'
Options / Configuration
| Field | Meaning | Required |
|---|---|---|
| visitorId | Opaque internal Grometrics visitor ID | visitorId or userId |
| userId | Customer-defined application ID resolved through identity links | visitorId or userId |
| externalSessionId | Your app visit ID. Events for the same site, person, and app visit stay together until more than 30 minutes without activity. | no |
| event / name | Custom event name | ✓ |
| eventId | Stable business event ID used for automatic retry deduplication | recommended for retryable events |
| dedupeKey | Optional repeat delivery key. When supplied, it takes precedence over the key generated from eventId. Keep it unchanged when retrying. | no |
| properties | Structured event metadata | no |
Send externalSessionId only when the event belongs to a person's app visit. Send timestamp as the time the event happened. Delayed events join the visit according to that time, and a delayed event can combine visits when it fills a gap. A gap of exactly 30 minutes stays in one visit.
Without externalSessionId, the event is saved on the person's profile without a visit. The response contains sessionId: null. It remains visible in Realtime activity, custom events, event goals, funnels, and Data Export. It does not add visits or active visitors. Visit counts may fall because background activity no longer creates visits.
Retry the same action with the same site, event name, and eventId. Grometrics returns the saved event, including when it has no visit or arrives again after 30 minutes. If you supply dedupeKey, that value decides whether a delivery is a repeat. Without either key, each delivery adds an event.
Do not infer ID types from prefixes
Internal IDs are opaque. Put values in visitorId, userId, or externalSessionId according to who generated them, not what the string looks like. The server events endpoint rejects sessionId; use externalSessionId for customer-owned correlation.
Legacy event migration
Existing integrations that previously put an application user ID in visitorId can temporarily send x-grometrics-identity-contract: legacy-user-id. Grometrics treats that value as userId and creates or resolves an opaque internal visitor. New integrations should always send userId explicitly.
What happens next
Call identify at signup or login so earlier browser activity and later backend events share one visitor timeline. Identify API
Was this page helpful?