Experiments API

Endpoints for retrieving, starting, and analyzing A/B experiments.

Retrieve an experiment

GET /api/v1/experiments/{experiment_id}

Retrieves an A/B experiment including its variants, traffic allocation, status, and target groups.

Response

{
  "id": "exp_abc123",
  "name": "FedAvg vs FedProx",
  "status": "running",
  "variants": [
    {"name": "control", "model_id": "mdl_001", "allocation": 0.5},
    {"name": "treatment", "model_id": "mdl_002", "allocation": 0.5}
  ],
  "target_groups": ["grp_ios_devices"],
  "created_at": "2025-07-01T10:00:00Z",
  "started_at": "2025-07-01T10:05:00Z"
}

---

Retrieve analytics

GET /api/v1/experiments/{experiment_id}/analytics

Returns aggregate analytics -- per-variant metrics, statistical significance, and sample sizes.

Response

{
  "experiment_id": "exp_abc123",
  "status": "running",
  "variants": [
    {"name": "control", "sample_size": 2450, "accuracy": 0.842, "loss": 0.391},
    {"name": "treatment", "sample_size": 2510, "accuracy": 0.871, "loss": 0.327}
  ],
  "p_value": 0.023,
  "significant": true,
  "confidence_level": 0.95
}

---

Start an experiment

POST /api/v1/experiments/{experiment_id}/start

Starts a configured experiment. Traffic is routed to variants according to allocation percentages. Returns 409 Conflict if already running.

Response

{
  "id": "exp_abc123",
  "status": "running",
  "started_at": "2025-07-01T10:05:00Z"
}

---

Errors

Status	Error	Description
400	bad_request	Invalid or missing request fields
401	unauthorized	Missing or invalid API key
404	not_found	Resource does not exist
409	conflict	Resource already exists or state conflict
429	rate_limited	Too many requests; check Retry-After
500	internal_error	Unexpected server error