# Experiment \[IMPORT]

```
POST 
/experiments/import
```

**Required Permissions**: `Experiment Admin` and (`Experiment Create` or `Experiment CreateFromTemplate`). Importing a feature (`type: feature`) requires the same permissions in the `Feature` category, and an iteration after the first also requires `Admin` in its predecessor's category.

Imports an experiment or feature from another system as a historical record. Most configuration fields are the same as in Experiment \[CREATE], although holdout, template and parent fields, for example, are not accepted, and import adds `source`, `seed`, `traffic_seed`, `datasource_id` and `timestamps`. `timestamps` records when each lifecycle action happened and who performed it. The final state is derived from those timestamps; the source system's workflow is not replayed. Everything is written in a single transaction, and unknown properties are rejected at every level of the request.

**Lifecycle timestamps**

* Actions are applied in the order `create`, `ready`, `development`, `start`, `full_on`, `stop`, `archive`, `unarchive`, regardless of their order in the JSON, and their `at` values must not decrease in that order. Each occurs at most once. Only `create` is required, and `ready` is optional, so `create` followed by `start` is valid.
* `stop` and `full_on` require `start` or `development`, `full_on` is only available for tests, and `unarchive` requires `archive`.
* `comment` is an array of up to 100 comments, which can occur at any point after `create`. A comment can reply to an earlier top-level comment by its index in the array, and a reply cannot be dated before the comment it replies to.
* Every `at` must be an ISO 8601 date-time with a full calendar date and `Z` or an explicit offset, and must not be in the future. Every `user_id` must be an existing user in your account; deactivated users are allowed.
* Without `start` or `development`, the experiment is imported as a draft (`created`). An optional `state` that contradicts the state derived from the timestamps is rejected with 422, so `ready` is never accepted.

**Features**

* `start` and `development` turn a feature on, and `stop` turns it off, so a single on/off cycle can be recorded. As in the Web Console, `stop` turns a feature off but leaves it running or in development. To import a feature that was closed by a restart, pass `state: "stopped"` and no `archive`.
* A feature that was turned on and then archived, without being unarchived, is imported as stopped. Archiving does not stop a test: an archived running test is imported as running.

**Validation**

* `unit_type` is required for every import, and a `test` always needs `required_alpha` and `required_power`, even as a draft.
* Every import that is not a draft, including closed history, must also include the fields a non-draft experiment needs: at least one application, an audience, `variants` matching `nr_variants` (numbered by position, names up to 48 characters), a complete `percentages` split, and, for a test, a primary metric and an `analysis_type`.
* An import whose final state is `stopped`, and which is not a feature, may skip the requirements that apply to new experiments: whether fully sequential analysis is enabled for your account, the configured limits on experiment payload size, required owners, tags and custom fields, the screenshots requirement, the limits on the number of secondary, guardrail and exploratory metrics, and archived or non-current metric versions.
* Every other import (draft, development, running, and any feature) must pass the same checks as creating the experiment and, for active states, starting it, except that a minimum detectable effect or maximum duration is only required for a running group sequential test that is not full on.
* Format and data-integrity checks apply to every import. Duplicate entries in `owners`, `teams`, `applications`, `variants`, `secondary_metrics`, `experiment_tags` or `variant_screenshots` are rejected.
* Only one iteration of an experiment name can be running or in development at a time, including archived iterations in those states.

**Iterations**

* Iteration 1 can only be imported when no iteration with that name exists; otherwise the request returns 409.
* Iteration N extends iteration N-1 with the same `name`, which must be the latest iteration. It inherits the predecessor's data source, `seed` and `traffic_seed` unless they are supplied.
* The predecessor must be closed (stopped, or a feature that is off), and the new iteration's `create` must not precede the predecessor's creation or closure. A feature imported as off without `state: "stopped"` stays running or in development, so only a draft or a closed iteration can follow it. For an active next iteration, import the predecessor with `state: "stopped"`.
* Iterations are never allocated automatically, and existing history is never changed.

**Retries and what is imported**

* An otherwise valid request for an existing `name` and `iteration` returns 409, even for an identical payload. If a request times out, check whether the experiment exists before retrying.
* The experiment's activity contains the original historical notes and a note recording the import, attributed to the caller.
* Holdouts, event and participant data, and metrics snapshots are not imported.

## Request

## Responses

* 200
* 400
* 401
* 403
* 409
* 422

OK

Bad Request - the body is not valid JSON, or a value was rejected when the record was written

Unauthorized

Forbidden - missing administrator or create permission in the experiment's category, or administrator permission in the predecessor's category

Conflict - an experiment with this name and iteration already exists, iteration 1 was sent for a name that already has iterations, or a conflicting write happened at the same time

Unprocessable Entity - the request body, configuration, chronology or history failed validation