API
Events and the collector
The batch format SDKs send, delivery guarantees and retries.
SDKs send two kinds of events: exposures (a user was put in an experiment variation) and track events (something the user did). They go in batches to the collector, which validates them and writes them to the analytics warehouse. You only need this page to build an SDK or send events from a system without one.
Sending a batch#
POST https://events.liftcanary.com/v1/batch
Content-Type: application/json
{
"sdkKey": "pk_...",
"sdk": { "name": "my-backend", "version": "1.0.0" },
"events": [
{
"type": "exposure",
"uuid": "3f0e6c1e-9a52-4a8e-8f53-0b1c2d3e4f50",
"timestamp": 1762500000000,
"userId": "user_8812",
"attributes": { "country": "TR", "device": "mobile" },
"flagKey": "new_checkout",
"ruleKey": "checkout_test",
"variationKey": "one_page",
"revision": 42
},
{
"type": "track",
"uuid": "a1b2c3d4-0000-4000-8000-000000000001",
"timestamp": 1762500042000,
"userId": "user_8812",
"eventKey": "purchase",
"value": 499.9,
"properties": { "currency": "TRY" }
}
]
}The body may also be sent as text/plain (what navigator.sendBeacon sends, which avoids a CORS preflight). Batches are limited to 512 KB.
Every event#
typerequired"exposure" | "track" | "identify" | |
uuidrequiredstring | Unique per event. Retries reuse it, so duplicates collapse. |
timestamprequirednumber | Milliseconds since the epoch, on the device. |
userIdrequiredstring | The user id the decision was made for. |
attributesobject | The user's attributes when it happened. |
Exposure#
flagKeyrequiredstring | |
ruleKeyrequiredstring | The experiment rule. |
variationKeyrequiredstring | |
revisionrequirednumber | Datafile revision the decision was made with. |
Track#
eventKeyrequiredstring | The event name, or a goal ID. |
valuenumber | Revenue, duration, count… |
propertiesobject | Anything else, for your own analysis. |
Identify#
A sign-in: userId is the known user and anonymousId the id they had before. Results then count both ids as one person (see From landing page to app). Send it once per pair; repeats are harmless.
anonymousIdrequiredstring | The visitor's anonymous id; must differ from userId. |
Responses and retries#
| Status | Meaning | The SDK should |
|---|---|---|
| 202 | Accepted. Invalid single events are dropped and reported in the response; the rest is stored. | drop the batch from its queue |
| 4xx (not 429) | The batch can never be accepted (unknown SDK key, malformed body, 403 origin_not_allowed). | drop it |
| 429, 5xx, network error | Temporary. | retry with exponential backoff (up to a minute), keeping the same uuids |
- The collector acknowledges only once the data is durable in the warehouse; nothing is held in its memory.
- Device clocks more than 5 minutes ahead are replaced with the server time (the original is kept). Events older than 30 days are rejected.
- SDK keys are checked against the API and cached for 60 seconds, so known keys keep working through a short API outage.
- For browser traffic, the page origin is recorded (Origin header, else Referer) for the Websites page, and checked against the allowed websites when blocking is on.