Events Endpoint

Record events

Submits a batch of analytics events for processing. SDKs should buffer events locally and flush them periodically rather than sending one event per request.

POST /events

Request body

{
  "events": [
    {
      "type": "Evaluation",
      "flagKey": "dark-mode",
      "userId": "user-123",
      "variation": "on",
      "timestamp": "2026-02-16T15:30:00Z",
      "metadata": {}
    }
  ]
}

Field	Type	Required	Description
events	SdkEventDto[]	Yes	Array of events to record

SdkEventDto

Field	Type	Required	Description
type	string	Yes	Event type (see below)
flagKey	string	Yes	Associated flag key
userId	string	No	User identifier
variation	string	No	Variation key involved
timestamp	string	Yes	ISO 8601 timestamp (UTC)
metadata	object	No	Arbitrary key-value pairs
prerequisiteKey	string	No	For an Evaluation event whose reason is prerequisite-failed, the parent flag that gated it
reason	string	No	For an Evaluation event, why that variation was served: rule-match, fallthrough, flag-disabled, prerequisite-failed, error or flag-not-found. Flag analytics uses it to show which part of the targeting served the traffic. Events without it count as an unknown source
ruleId	string	No	The id of the targeting rule that matched, when reason is rule-match

Event types

Type	Description
Evaluation	A flag was evaluated
Impression	A flag value was exposed to a user
Identify	A user was identified
Custom	A custom tracking event

Response

Returns 202 Accepted with an empty body. Events are queued for asynchronous processing.

Errors

• 401 Unauthorized — Invalid or missing SDK key.

SDK implementation notes

• Buffer events in memory and flush them on a timer (e.g., every 30 seconds) and when the buffer reaches a size threshold (e.g., 100 events).
• Flush remaining events when the client is closed.
• If a flush fails, retain the events and retry on the next interval.

See also

• API Overview — authentication, rate limiting, and all endpoints
• Evaluate Endpoint — evaluate flags for user contexts
• Streaming Endpoint — real-time flag updates via SSE
• SDK Overview — official SDKs handle event buffering automatically