# Experiment

URL: /business/nouns/experiment · Id: `noun:experiment`

> An Experiment is a test of a Hypothesis that varies copy or behavior through Flags and judges the variants by a primary Metric.

An Experiment is a test of a [Hypothesis](/business/nouns/hypothesis) that varies copy or behavior through [Flags](/business/nouns/flag) and judges the [Variants](/business/nouns/variant) by a primary [Metric](/business/nouns/metric). It ends in a `decision`: ship, kill, or iterate.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `variants` | `json` | Yes | The variants and their split. |
| `decision` | `string` | No | One of `ship`, `kill`, or `iterate`. |

## Object
```json
{
  "$id": "https://api.sb/ledgerlark.com/experiments/experiment_1",
  "$type": "Experiment",
  "variants": {},
  "decision": "ship"
}
```

## Relationships
- <a id="rel-assigns-with"></a>An Experiment **assigns with** many [Flags](/business/nouns/flag): [Flags](/business/nouns/flag) split units across an Experiment’s [Variants](/business/nouns/variant) and log each assignment with its propensity. `assignsWith`, inverse [`assigns`](/business/nouns/flag#rel-assigns).
- <a id="rel-measures"></a>An Experiment **measures** many [Metrics](/business/nouns/metric): one primary [Metric](/business/nouns/metric) judges an Experiment’s [Variants](/business/nouns/variant); guardrail Metrics stop it. `measures`, inverse [`measuredBy`](/business/nouns/metric#rel-measured-by).
- <a id="rel-offers"></a>An Experiment **offers** many [Variants](/business/nouns/variant): the [Variants](/business/nouns/variant) the Experiment can assign, the control among them. `offers`, inverse [`offeredBy`](/business/nouns/variant#rel-offered-by).
- <a id="rel-readouts"></a>An Experiment **has** many [Readouts](/business/nouns/readout): the Experiment the result belongs to; the learn step drafts the next [Variant](/business/nouns/variant) from it. `readouts`, inverse [`reads`](/business/nouns/readout#rel-reads).
- <a id="rel-tests"></a>An Experiment **tests** one [Hypothesis](/business/nouns/hypothesis): each Experiment settles one [Hypothesis](/business/nouns/hypothesis); many Experiments test one Hypothesis in turn. `tests`, inverse [`testedBy`](/business/nouns/hypothesis#rel-tested-by).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `draft` (first) | Its variants and Metrics are set, and no traffic is split yet. | `running` by [Experiment.start](/business/nouns/experiment/start) |
| `running` | Traffic is split across its variants while its Metrics are measured. | `concluded` by [Experiment.conclude](/business/nouns/experiment/conclude) |
| `concluded` | It ended with a Decision to ship, kill, or iterate. | None: it ends here. |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Experiment.conclude](/business/nouns/experiment/conclude) | Conclude ends an Experiment with a decision to ship, kill, or iterate, recorded as a Decision. | [Strategist](/agents/founding/strategist) | [`Experiment.concluded`](/business/events/Experiment.concluded) | None. |
| [Experiment.start](/business/nouns/experiment/start) | Start opens an Experiment, splits traffic across its variants, and begins measuring its primary and guardrail Metrics. | [Strategist](/agents/founding/strategist) | [`Experiment.started`](/business/events/Experiment.started) | None. |
| <a id="create"></a>[Experiment.create](/business/nouns/experiment/create) | Creates an Experiment. Inherited from [Noun](/business/nouns/noun). | None. | `Experiment.created` | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Experiment.get](/business/nouns/experiment/get) | Returns one Experiment by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Experiment.list](/business/nouns/experiment/list) | Returns Experiments, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

An Experiment is kept forever and never edited: it has no `update` or `delete`.

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Experiment.create` | Yes | Yes | Yes | No |
| `Experiment.get` | Yes | Yes | Yes | Yes |
| `Experiment.list` | Yes | Yes | Yes | Yes |
| `Experiment.conclude` | Yes | Yes | Yes | No |
| `Experiment.start` | Yes | Yes | Yes | No |

## Call it

**Ask**

```text
Start the latest experiment.
```

**API**

```bash
curl -X POST https://api.sb/patentpad.com/experiments/experiment_1/start \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/patentpad.com",
  "experiment": {
    "$id": "https://api.sb/patentpad.com/experiments/experiment_1",
    "$type": "Experiment",
    "variants": {}
  },
  "action": {
    "$id": "https://api.sb/patentpad.com/actions/action_1",
    "operation": "Experiment.start",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/patentpad.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const experiment = await $.Experiment.start({ experiment: 'experiment_1' })
```

**CLI**

```bash
npx startup-builder do Experiment.start --json '{"experiment":"experiment_1"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Experiment.start({ experiment: 'experiment_1' })"
  }
}
```

## Example
An Experiment tests whether a $0 tier raises paid conversion. A Flag shows the tier to half of new [Visitors](/business/nouns/visitor); paid conversion at 30 days decides, and the `decision` reads `ship`.