---
title: Sending events to Venom Experiments
description: 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.
section: cloud
order: 250
audience: [builder, agent, user]
sources: [services/nodejs-cloud/sdk/flags, services/nodejs-cloud/app/experiments/sdk, services/nodejs-cloud/lib/analytics]
features: [cloud.experiments]
---

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](/docs/cloud/flags.md) project and environment and use that environment's keys; there is no second key
type.

## Track events from the TypeScript SDK

```ts
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`.

```json
{
  "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.
