Sending events to Venom Experiments
Track product events from your own app with the Flags SDK's track(), what the ingest endpoint accepts, its limits and retention, and how exposures are recorded.
Venom Experiments (ADR 0054) analyses what your own app sends it. This page covers the sending side: product events
with track(), the exposures that say who saw which variation of an experiment, and the endpoint behind both. Events
belong to a Venom Flags project and environment and use that environment's keys; there is no second key
type.
Track events from the TypeScript SDK
import { VenomFlags } from "./venom-flags/sdk/flags/index.ts";
const flags = new VenomFlags({ sdkKey: process.env.VENOM_FLAGS_SDK_KEY!, baseUrl: "https://cloud.usevenom.dev" });
// event, who it happened to (a Flags context), an optional number, optional properties
flags.track("checkout_completed", { kind: "user", key: "u-1" }, 42.5, { plan: "pro" });
// A worker serving one user at a time can set the context once:
flags.identify({ kind: "user", key: "u-1" });
flags.track("checkout_completed", 42.5, { plan: "pro" });track()never throws and never waits. Events are queued and sent in the background, everytrackFlushMs(default 5 s) or whentrackBatchevents (default 500) are queued.- A failed send (network error,
429,5xx) is retried with backoff, four attempts in all. A batch the server refuses for another reason (401,400) is dropped and reported toonError. The queue holds 10,000 events; past that the oldest go.close()sends what is left. - A multi-kind context counts for its
user, else its first kind. The unit (kind and key) is what experiments count. trackFlushMs: 0turns tracking off.- Exposures are automatic. When a flag serves a unit inside a running experiment (the evaluation's reason says
inExperiment), the SDK posts one exposure per experiment and unit. Later exposures of the same unit are ignored, so a unit counts once, in the first variation it saw. - The SDK posts only to the
baseUrlyou give it. There is no autocapture, no page-view script and no session recording.
The endpoint
POST /experiments/sdk/events, with Authorization: vfs_… (or vfm_…), or x-venom-client-id: vfc_… from a
browser. Events sent with the public client-side id are marked client.
{
"events": [
{ "event": "checkout_completed", "unit": { "kind": "user", "key": "u-1" }, "value": 42.5, "props": { "plan": "pro" }, "ts": 1790000000000 }
],
"exposures": [
{ "experiment": "exp_123", "variation": "1", "unit": { "kind": "user", "key": "u-1" } }
]
}It answers 202 with { "accepted": 1, "exposures": 1, "rejected": 0 }. An event that fails validation is dropped
and counted in rejected (the first few reasons are in errors); the rest of the batch is kept.
| Limit | Value |
|---|---|
| Events or exposures per batch | 1000 each |
| Body | 512 KB |
| Event name | 1 to 128 printable characters |
| Unit | kind (letters, digits, _, -; default user) and key (up to 256 characters) |
value |
one finite number |
props |
a JSON object of at most 2 KB |
ts |
milliseconds or an ISO string, within the last 7 days and 5 minutes ahead; otherwise the arrival time is used |
| Daily events per organisation | 5,000,000 unless the organisation's setting says otherwise. Past it the answer is 429 with Retry-After (seconds to 00:00 UTC) |
A server that has seen your key recently does not look it up again for 30 seconds, so a rotated key can still send for that long.
Retention
Raw events are kept for 90 days by default; an organisation's setting can make it 7 to 365 days (set by an operator for now; the app gets a control with the Experiments pages). Daily per-unit rollups, which experiments, retention and metric trends read, are kept 13 months. Exposures are kept with their experiment.