Experiments (A/B Testing)

Experiments

Run A/B and multivariate experiments with authenticated management and public assignment/tracking endpoints.

Audience: Optimization teams running conversion tests on campaigns, widgets, and recommendation placements.

Critical: Public assignment and tracking endpoints require siteKey and are throttled for abuse protection (assign: 60/min, tracking: 120/min).

Campaigns Widgets Funnels Analytics

Who This Page Is For

Use this page when you need a reliable experiment lifecycle contract from creation to result readout, including storefront variant assignment and conversion tracking.

Quick Start (2-5 Minutes)

Create experiment

Define hypothesis, variants, goals, and traffic split.

POST /api/v1/experiments

Start test

Move experiment to running state when QA is complete.

POST /api/v1/experiments/:id/start

Assign variant on storefront

Fetch visitor assignment using siteKey + visitorId.

GET /api/v1/public/experiments/assign?siteKey=SITE_KEY&visitorId=VISITOR_ID

Track experiment events

Send impression/conversion and custom events to public endpoints.

POST /api/v1/public/experiments/track?siteKey=SITE_KEY
POST /api/v1/public/experiments/track-event?siteKey=SITE_KEY

Read results and complete

Inspect statistical output and mark experiment completed.

GET /api/v1/experiments/:id/results
POST /api/v1/experiments/:id/complete

Experiment endpoints

POST   /api/v1/experiments
GET    /api/v1/experiments
GET    /api/v1/experiments/:id
PUT    /api/v1/experiments/:id
POST   /api/v1/experiments/:id/start
POST   /api/v1/experiments/:id/pause
POST   /api/v1/experiments/:id/complete
GET    /api/v1/experiments/:id/results
DELETE /api/v1/experiments/:id
GET    /api/v1/public/experiments/assign?siteKey=:siteKey&visitorId=:visitorId
POST   /api/v1/public/experiments/track?siteKey=:siteKey
POST   /api/v1/public/experiments/track-event?siteKey=:siteKey

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`name`	Required	`string`	Create/update experiment	Experiment label used in results and reporting.
`siteId`	Required	`uuid`	Create experiment	Site boundary for traffic assignment and analytics.
`type`	Required	`ab_test \| multivariate \| split_url`	Experiment design	Defines experimentation model.
`variants[]`	Required	`array`	Assignment and analysis	Variant definitions including traffic split and target config.
`eventType`	Required	`impression \| conversion`	public/experiments/track	Primary outcome tracking on runtime endpoint.
`siteKey`	Conditional	`string`	Public assignment/track endpoints	Pass via query parameter; body fallback remains accepted for compatibility.

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Operate experiment lifecycle in admin	*/api/v1/experiments authenticated endpoints**	Full CRUD + status transitions with RBAC.
Assign variant to anonymous visitor	GET /api/v1/public/experiments/assign	Deterministic runtime assignment flow.
Track impression or conversion outcome	POST /api/v1/public/experiments/track	Standard event contract for experiment stats.
Track extra behavioral signal	POST /api/v1/public/experiments/track-event	Supports custom event telemetry.
Pause test due to incident	POST /api/v1/experiments/:id/pause	Fast rollback while preserving accumulated data.

Common Errors and Fixes

Public assign endpoint returns siteKey required

Cause: siteKey missing in query and body.

Fix: Send siteKey in query string for maximum compatibility.

No conversions in results

Cause: Runtime is only sending assignment but not track/track-event calls.

Fix: Wire conversion events to public experiment tracking endpoints.

Experiment cannot start

Cause: Invalid variant setup or missing permissions for update actions.

Fix: Validate variant payload and role permissions before start.

Unexpected 429 on public tracking

Cause: Throttling triggered due to high-frequency calls.

Fix: Batch frontend actions sensibly and avoid duplicate submissions.

Production Checklist

Experiment has explicit primary goal and success threshold.Required
Variant traffic splits total 100% and are validated pre-launch.Required
Public assignment and track endpoints are both integrated in storefront.Required
Pause/complete operational runbook exists for incidents.Required
Result reviews include both uplift and sample-size context.Required