Skip to main content
POST
Create Experiment

Autorisationer

Authorization
string
header
påkrævet

An Account API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.

Overskrifter

Idempotency-Key
string

A unique key that makes this request safe to retry. See Idempotent requests.

Maximum string length: 255
Eksempel:

"d9105228-4a08-46b1-8b91-42fed586d383"

Api-Version-Date
string

Pins the request to a dated API version.

Eksempel:

"2026-11-17"

Krop

application/json
account_id
string
påkrævet

Owning account ID. Required; ownership cannot change.

Eksempel:

"biz_xxxxxxxxxxxxxx"

flag_key
string
påkrævet

Developer-chosen handle referenced from code, used in evaluation and results calls. Interchangeable with the returned expt_ id anywhere the API takes an experiment identifier.

Eksempel:

"checkout_redesign_v2"

bucket_by
enum<string>

Randomization unit, and the only identity the assignment is keyed on — evaluation fails rather than falling back to another. user (default) uses subject[user_id]; account uses subject[account_id], so every user of an account gets the same arm; anonymous uses the anonymous id and survives sign-in. Fixed after creation.

Tilgængelige muligheder:
user,
account,
anonymous
Eksempel:

"user"

control
object
hypothesis
string | null

Required for full experiments; rejected on feature flags. Structure it as "If we [change] for [cohort], then [measurable behavior] will [increase/decrease], resulting in [business outcome], because [evidence]. Created by [name]." Evidence should be something real — a baseline number, a funnel breakdown — not a guess, and [name] is you, not something to leave blank.

Eksempel:

"If we send a blueprint nudge email 30 minutes after business creation, then GTV within 10 hours will increase among newly created businesses, resulting in more new business operators generating GTV within 10 hours, because operators currently land on an empty dashboard with no concrete next step. Created by Jane Doe."

metadata
object

Up to 20 key-value pairs you can attach to the experiment for your own use, such as which pages it changes. Keys are at most 40 characters and values at most 500.

name
string

Human-readable display name. Defaults to flag_key when omitted.

Eksempel:

"Checkout Redesign V2"

Resource owned by the account that this experiment is bound to, such as an app or product. null when unbound. Fixed once the experiment first activates.

variants
object[]

Treatment arms to create. Users outside every arm form the implicit control group. Required unless feature_flag_only is true.

Svar

experiment created

account_id
string
påkrævet

Owning account ID.

Eksempel:

"biz_xxxxxxxxxxxxxx"

assignment_seed
string
påkrævet

Assignment hashes UTF-8 seed + subject ID with CRC32 modulo 100 and selects the stored end-exclusive range.

Eksempel:

"checkout_redesign_v21768435200"

configuration_revision
integer
påkrævet

Revision of the serving configuration. Increments on every configuration change, so a cached definition with a lower revision is stale. Does not change the assignment seed.

Eksempel:

1

control
object
påkrævet
flag_key
string
påkrævet

Developer-chosen handle referenced from code. Anywhere the API takes an experiment identifier, the expt_ id and the flag_key are interchangeable.

Eksempel:

"checkout_redesign_v2"

id
string
påkrævet

Unique identifier for the experiment, prefixed expt_.

Eksempel:

"expt_xxxxxxxxxxxxxx"

name
string
påkrævet

Human-readable display name.

Eksempel:

"Checkout Redesign V2"

Resource owned by the account that this experiment is bound to, such as an app or product. null when unbound. Fixed once the experiment first activates.

status
enum<string>
påkrævet

Lifecycle state. draft — not yet live; active — currently running; paused — traffic paused; ended — concluded.

Tilgængelige muligheder:
draft,
active,
paused,
ended
Eksempel:

"draft"

updated_at
string<date_time> | null
påkrævet
Eksempel:

"2026-01-01T12:00:00.000Z"

variants
object[]
påkrævet

Treatment arms. Users outside every arm's allocation form the implicit control group. Weights only ever grow and arms are never removed, so a user moves from control into a treatment at most once.

bucket_by
enum<string> | null

Randomization unit — user buckets each user independently, account buckets whole accounts (every user of an account gets the same arm). null for feature flags.

Tilgængelige muligheder:
user,
account,
anonymous
Eksempel:

"user"

created_at
string | null

When the experiment was created, as an ISO 8601 timestamp.

Eksempel:

"2026-01-01T12:00:00.000Z"

created_by
string | null

ID of the user who created the experiment, prefixed user_. null for experiments created before creators were recorded.

Eksempel:

"user_xxxxxxxxxxxxxx"

ended_at
string | null

When the experiment stopped collecting data, as an ISO 8601 timestamp. null while still running.

Eksempel:

"2026-01-01T12:00:00.000Z"

findings
string | null

What was learned and why this outcome, recorded when the experiment was ended. null until then.

Eksempel:

"Treatment lifted conversion 8%"

hypothesis
string | null

Hypothesis for this experiment. null when none is set, and always null for feature flags.

Eksempel:

"Users will convert more"

metadata
object

Key-value pairs attached when the experiment was created. Empty when none were set.

Eksempel:
started_at
string | null

When the experiment began collecting data, as an ISO 8601 timestamp. null for drafts.

Eksempel:

"2026-01-01T12:00:00.000Z"

winning_arm
string | null

The treatment that won, set when the experiment was ended. Once set, every evaluation returns this arm to every caller regardless of targeting or allocation, and no further exposures are recorded. null means control won — an ended experiment with no winning arm evaluates to control for everyone. Always null for feature flags, which simply evaluate to disabled once ended.

Eksempel:

"treatment"