Skip to main content
Ingests events from SDKs and custom integrations. Events are processed for real-time aggregation and stored for optimization.

​
Request

POST /v1/events
Also accepts POST /v1/events/batch as an alias.

​
Headers

HeaderRequiredDescription
AuthorizationYesBearer traffical_sk_... (requires sdk:write scope)
Content-TypeYesapplication/json

​
Body

An array of events (maximum 1000 per request): 
{
  "events": [
    {
      "type": "exposure",
      "orgId": "org_acme",
      "projectId": "proj_marketplace",
      "env": "production",
      "unitKey": "user_789",
      "timestamp": "2026-05-21T10:30:00Z",
      "decisionId": "dec_abc123",
      "layers": [
        {
          "layerId": "layer_checkout",
          "policyId": "policy_color_test",
          "allocationName": "treatment",
          "bucket": 7420
        }
      ]
    },
    {
      "type": "track",
      "orgId": "org_acme",
      "projectId": "proj_marketplace",
      "env": "production",
      "unitKey": "user_789",
      "timestamp": "2026-05-21T10:35:00Z",
      "event": "purchase",
      "properties": { "order_total": 49.99, "currency": "USD" },
      "decisionId": "dec_abc123"
    }
  ]
}

​
Event schemas

​
Exposure event

Tracked automatically by SDKs when parameters are resolved.
FieldTypeRequiredDescription
type"exposure"YesEvent type
unitKeystringYesUser identifier for bucketing
timestampstringYesISO 8601 timestamp
layersLayerAssignment[]YesLayer assignments (see below)
decisionIdstringNoLinks exposure to subsequent track events
userIdstringNoUser identifier (if different from unitKey)
sessionIdstringNoSession identifier
sdkNamestringNoSDK name (for example, js-client)
sdkVersionstringNoSDK version
LayerAssignment:
FieldTypeDescription
layerIdstringLayer ID
policyIdstringPolicy that was applied
allocationNamestringAllocation name (for example, control, treatment)
bucketnumberComputed bucket number (0–999)

​
Track event

Custom events sent by your code for analytics and optimization.
FieldTypeRequiredDescription
type"track"yesEvent type
orgId, projectId, envstringyesIdentify the scope
unitKeystringyesUser identifier (or whatever the project’s unit key is)
timestampstringyesISO 8601 timestamp
eventstringyesEvent name (e.g. purchase, signup)
propertiesRecord<string, unknown>noEvent payload (typed via generate-types)
decisionIdstringnoLinks to the decision that preceded this event
attributionTrackAttribution[]noExplicit attribution metadata (advanced)

​
Decision event

Logged by the server-side /v1/decide endpoint.
FieldTypeRequiredDescription
type"decision"YesEvent type
unitKeystringYesUser identifier
timestampstringYesISO 8601 timestamp
layersLayerAssignment[]YesLayer assignments
latencyMsnumberNoProcessing latency in milliseconds

​
Response

​
200 OK

{
  "accepted": 2,
  "written": 2
}
FieldTypeDescription
acceptednumberNumber of valid events in the request
writtennumberNumber of events successfully processed

​
400 Bad request

{
  "error": "Bad Request",
  "message": "events must be a non-empty array (max 1000)"
}

​
401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired API key"
}