LiftCanary

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#

HTTP
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"
uuidrequired
string
Unique per event. Retries reuse it, so duplicates collapse.
timestamprequired
number
Milliseconds since the epoch, on the device.
userIdrequired
string
The user id the decision was made for.
attributes
object
The user's attributes when it happened.

Exposure#

flagKeyrequired
string
ruleKeyrequired
string
The experiment rule.
variationKeyrequired
string
revisionrequired
number
Datafile revision the decision was made with.

Track#

eventKeyrequired
string
The event name, or a goal ID.
value
number
Revenue, duration, count…
properties
object
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.

anonymousIdrequired
string
The visitor's anonymous id; must differ from userId.

Responses and retries#

StatusMeaningThe SDK should
202Accepted. 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 errorTemporary.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.