Skip to content
Docs menu

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.

View .md

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, every trackFlushMs (default 5 s) or when trackBatch events (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 to onError. 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: 0 turns 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 baseUrl you 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.