How to Set Up Your First Bandit Experiment in 5 Minutes

What You'll Build

By the end of this tutorial, you'll have a running bandit experiment that assigns users to different headline variants and tracks which one gets the most clicks. The entire setup takes about five minutes.

Prerequisites

You need a Bandit platform account with an API key. If you don't have one yet, sign up and grab your key from the dashboard under Settings > API Keys.

Step 1: Create the Experiment

From the dashboard, go to Experiments > New Experiment and fill in:

• Name: Homepage Headline Test
• Algorithm: Thompson Sampling (recommended for most cases)
• Content Type: Text > Plain Text
• Assignment TTL: 24 hours (a user sees the same variant for a full day)

Then add your treatments:

Hit Create. Your experiment is now in draft status. When you're ready to start collecting data, change the status to Active.

Step 2: Install the SDK

Install the Bandit SDK in your project:

npm install @bandits/sdk

Then initialize the client with your API key:

import { BanditsClient } from '@bandits/sdk';

const client = new BanditsClient({
  apiUrl: 'https://runbandit.com',
  apiKey: 'your-api-key-here'
});

Step 3: Get an Assignment

When a user loads your page, request an assignment from the experiment. The algorithm selects the best treatment based on what it's learned so far.

const assignment = await client.getAssignment(
  'your-experiment-id',  // from the dashboard
  'user-123'             // your user's unique ID
);

// assignment.treatment.config contains your variant data
const headline = assignment.treatment.config.headline;

// Render the headline
document.querySelector('h1').textContent = headline;

The getAssignment call does several things behind the scenes:

1. Checks if this user already has a cached assignment (within TTL)
2. If not, runs the bandit algorithm to select a treatment
3. Stores the assignment in Redis with the configured TTL
4. Logs an ASSIGNMENT event for analytics
5. Returns the treatment with its config and a unique assignment ID

Step 4: Track Conversions

When the user takes the desired action (clicks a button, signs up, makes a purchase), track it as an event tied to the assignment:

await client.trackEvent({
  assignmentId: assignment.id,
  eventType: 'CONVERSION',
  value: 1
});

This is the feedback loop that makes bandit algorithms work. Each conversion event updates the algorithm's understanding of which treatment performs best. Over time, the algorithm shifts more traffic to the winning variant.

Try the Full Integration

Use the playground below to see the complete code and test the API calls interactively. You can modify the experiment ID, user ID, and event parameters.

pnpm add @runbandit/sdk

import { BanditClient } from '@runbandit/sdk'

const bandit = new BanditClient({
  apiUrl: 'https://runbandit.com',
  apiKey: 'your-api-key'
})

const assignment = await bandit.getAssignment(
  'experiment-headline',
  'user-123',
  { deviceType: 'mobile', location: 'US' }
)

// Use the assigned variant
document.querySelector('#headline').textContent =
  assignment.config.content

bandit.trackEvent({
  assignmentId: assignment.assignmentId,
  eventType: 'CONVERSION',
  value: 29.99,
  metadata: { product: 'premium-plan' }
})

Step 5: Watch the Results

Back in the dashboard, navigate to your experiment. You'll see:

• Traffic allocation: how the algorithm distributes users across treatments
• Conversion rates: per-treatment success rates with confidence intervals
• Cumulative conversions: total conversions over time
• Lift: how each treatment performs relative to the control

In the early rounds, traffic is distributed more evenly as the algorithm explores. As data accumulates, you'll see traffic concentrate on the best-performing variant. With Thompson Sampling, this transition happens naturally without any manual intervention.

What Happens Next

You don't need to manually "call" the experiment. As the bandit collects more conversion data, it automatically:

• Shifts traffic toward higher-performing treatments
• Reduces exploration as confidence increases
• Maintains enough exploration to detect if a previously losing variant improves

If you want to add new treatments later (a new headline idea), just add them in the dashboard. The algorithm will explore the new treatment enough to estimate its performance, then incorporate it into the overall optimization.

Common Patterns

Tracking revenue instead of conversions:

await client.trackEvent({
  assignmentId: assignment.id,
  eventType: 'CONVERSION',
  value: 49.99,  // revenue in dollars
  metadata: { plan: 'pro' }
});

Passing context for contextual bandits:

const assignment = await client.getAssignment(
  'experiment-id',
  'user-123',
  { deviceType: 'mobile', country: 'US', isNewUser: true }
);

Batch event tracking for high-volume pages: The SDK automatically batches events. Call trackEvent as often as needed, and the SDK flushes in configurable intervals.

Recap

Five steps, five minutes:

1. Create the experiment and treatments in the dashboard
2. Install the SDK in your project
3. Get assignments when users load the page
4. Track conversions when users take action
5. Watch the algorithm optimize in real time

The algorithm handles the hard part. You just need to connect the assignment to your UI and report back when something good happens.