`group.experiment()`

Selects and executes a single variant from a set of options. The selection is memoized as a durable step, so the same variant runs on retries and replays.

`group.experiment(id, options): Promise`

Name
id
Type
string
Required
required
Description
A unique identifier for the experiment. Used in logs and to memoize the variant selection across retries and replays.
Name
options
Type
object
Required
required
Description
Configuration for the experiment:
Properties
- Name
  variants
  Type
  Record<string, () => unknown>
  Required
  required
  Description
  A map of variant names to callbacks. Each callback should contain one or more step.* calls. Only the selected variant's callback is executed.
- Name
  select
  Type
  ExperimentSelectFn
  Required
  required
  Description
  A selection strategy that determines which variant to run. Use one of the built-in strategies: experiment.fixed(), experiment.weighted(), experiment.bucket(), or experiment.custom().
- Name
  withVariant
  Type
  boolean
  Required
  optional
  Description
  When true, the return value includes the selected variant name alongside the result. Defaults to false.

Basic usage

const result = await group.experiment("my-experiment", {
  variants: {
    a: () => step.run("variant-a", () => doA()),
    b: () => step.run("variant-b", () => doB()),
  },
  select: experiment.weighted({ a: 50, b: 50 }),
});

With variant name returned

const { result, variant } = await group.experiment("my-experiment", {
  variants: {
    a: () => step.run("variant-a", () => doA()),
    b: () => step.run("variant-b", () => doB()),
  },
  select: experiment.fixed("a"),
  withVariant: true,
});
// variant === "a"

Every variant callback must invoke at least one step.* tool (e.g., step.run()). Code that runs outside of a step is not memoized and will re-execute on every replay. The SDK throws a NonRetriableError if a variant completes without calling any step tools.

Selection strategies

Import the experiment object from the inngest package:

import { experiment } from "inngest";

`experiment.fixed(variantName)`

Always selects the specified variant. Useful for manual overrides or testing a specific code path.

select: experiment.fixed("control")

`experiment.weighted(weights)`

Weighted random selection, seeded with the current Inngest run ID. Deterministic: the same run always gets the same variant, even across retries.

select: experiment.weighted({ control: 80, treatment: 20 })

Weights are relative, not percentages. { a: 1, b: 3 } gives a a 25% chance and b a 75% chance.

`experiment.bucket(value, options?)`

Consistent hashing. The same input value always maps to the same variant. Useful for user-level bucketing where a user should see the same variant across multiple runs.

select: experiment.bucket(event.data.userId, {
  weights: { control: 70, treatment: 30 },
})

When weights are omitted, equal weights are derived from the variant names:

select: experiment.bucket(event.data.userId)

If value is null or undefined, the SDK hashes an empty string and attaches a warning to the step metadata.

`experiment.custom(fn)`

Provide your own selection logic. The function can be synchronous or asynchronous. The result is memoized durably, so it only runs once per function run.

select: experiment.custom(async () => {
  const flag = await getFeatureFlag("checkout-variant");
  return flag; // Must return a key from `variants`
})

The custom function must return a string that matches one of the keys in variants. If it returns an unknown variant name, the SDK throws a NonRetriableError.

Observability

The selection step carries experiment metadata: the experiment name, selected variant, strategy, available variants, and weights. This metadata is visible in the Inngest dashboard.

Steps executed within the selected variant's callback also carry experiment context, so you can trace which experiment and variant produced each step in a run.