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 | Site-scoped customer session correlation value; never a Session primary key | no |
| event / name | Custom event name | ✓ |
| eventId | Stable business event ID used for automatic retry deduplication | recommended for retryable events |
| properties | Structured event metadata | no |
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?