Skip to main content

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​

OK