Sign in

v4

latestOpenAPI 3.0.02026-08-04109113304.5 KB
Experiments

Update an Experiment

Update an experiment by ID.

patch/experiments/{experiment_id}

Path parameters

experiment_idinteger required

The Experiment ID of the Experiment you want to change

Query parameters

action'publish' | 'start' | 'pause' | 'resume' | 'unarchive'

Action to change the state of the experiment. publish saves and stages your experiment. If you have not started your experiment or the experiment is paused, your changes will not be visible to visitors when you publish. start makes your experiment live to all visitors who are in your targeted audience and changes the status to running. pause stops the experiment and changes the status to paused. No new visitors will see a paused experiment until you restart it. See Differences among publish, start, and pause for details. resume resumes the experiment from a paused status without publishing any new changes. Status will be running. unarchive unarchives an archived experiment. Status will be paused.

Request body

audience_conditionsstring

The audiences that should see this experiment. To target everyone, use the string "everyone". Multiple audiences can be combined with "and" or "or" using the same structure as audience conditions

custom_field_valuesobject

Map of custom field api_name to value for the Experiment's parent Campaign. Keys correspond to the api_name of a custom field definition for the Project, and values are typed according to that definition's field_type. Updating these values on an A/B or Multivariate experiment updates the parent Campaign. Not supported for personalization experiences — update those via the parent Campaign endpoint. Send an empty object to clear all values.

descriptionstring

The description or hypothesis for an Experiment

environmentsobject

String identifier for the Experiment's status in each Environment based on the environment key.

feature_idinteger

The ID of a Feature to attach to the Experiment. This turns an Experiment into a Feature Test.

holdbackinteger

Percent of traffic to exclude from the experiment, measured in basis points. 100 basis points = 1% traffic. For example, a value of 9900 would mean that 1% of visitors will be eligible for the experiment. This is only applicable for Web.

keystring

Unique string idz for this Experiment within the Project. Only applicable for Full Stack and Mobile projects.

namestring

Name of the Experiment

page_idsinteger[]

A list of Page IDs used in the Experiment. Only url_targeting or page_ids can be used when updating an experiment, but not both.

traffic_allocationinteger

Percent of traffic allocated for the experiment, measured in basis points. 100 basis points = 1% traffic. For example, a value of 5500 would mean that 55% of visitors will be eligible for the experiment. This is only applicable for Full Stack.

Example request

{
  "audience_conditions": "[\"and\", {\"audience_id\": 7000}, {\"audience_id\": 7001}]",
  "changes": [
    {
      "dependencies": [
        "993fd09c-b64a-4c13-95a9-13b3ed2c454e",
        "95cf0144-fb63-431d-829b-193fe55ada18"
      ],
      "name": "Setting button text",
      "selector": "head",
      "value": "window.someGlobalFunction();"
    }
  ],
  "description": "AB Test to see if the Blue Button converts more visitors",
  "feature_id": 1000,
  "holdback": 5000,
  "key": "home_page_experiment",
  "name": "Blue Button Experiment",
  "schedule": {
    "start_time": "2019-02-20T15:00",
    "stop_time": "2019-02-20T18:00",
    "time_zone": "America/New_York"
  },
  "traffic_allocation": 5000,
  "url_targeting": {
    "activation_code": "function callbackFn(activate, options) { activate(); }",
    "activation_type": "callback",
    "conditions": "[\"and\", {\"type\": \"url\", \"match_type\": \"substring\", \"value\": \"optimize\"}]",
    "edit_url": "https://www.optimizely.com",
    "key": "home_page",
    "page_id": 6700
  },
  "variations": [
    {
      "actions": [
        {
          "changes": [
            {
              "allow_additional_redirect": true,
              "async": true,
              "attributes": {
                "class": "new_class",
                "style": "background-color:blue",
                "text": "Some nice message"
              },
              "selector": "#my_div",
              "type": "attribute"
            }
          ],
          "page_id": 5678
        }
      ],
      "variation_id": 1234,
      "weight": 5000
    }
  ],
  "whitelist": [
    {
      "user_id": "user_1",
      "variation_id": 12345
    }
  ]
}

Response

Successfully updated Experiment

allocation_policystring

Traffic allocation policy across variations in this experiment

audience_conditionsstring

The audiences that should see this experiment. To target everyone, use the string "everyone" or omit this field. Multiple audiences can be combined with "and" or "or" using the same structure as audience conditions

campaign_idinteger

For Personalization experiences, this ID corresponds to the parent Campaign. For standalone experiments this campaign_id does not correspond to a campaign object.

createdstring date-time

The time when the Experiment was initially created

custom_field_valuesobject

Map of custom field api_name to value for the Experiment's parent Campaign. Keys correspond to the api_name of a custom field definition for the Project, and values are typed according to that definition's field_type. Returns an empty object when no values are set. May be set when creating an Experiment; on projects with required custom fields these values are mandatory.

descriptionstring

The description or hypothesis for an Experiment

earlieststring date-time

The first time the Experiment was activated

environmentsobject

String identifier for the Experiment's status in each Environment based on the environment key.

feature_idinteger

The ID of a Feature to attach to the Experiment. This turns an Experiment into a Feature Test.

feature_keystring

The key for the Feature attached to the Experiment. Applies to Feature Tests only. Valid keys contain alphanumeric characters, hyphens, and underscores, and are limited to 64 characters.

feature_namestring

The feature flag name to display in the Optimizely app. Whitespaces and other non-alphanumeric characters allowed. Defaults to feature key if left empty.

holdbackinteger

Percent of traffic to exclude from the experiment, measured in basis points. 100 basis points = 1% traffic. For example, a value of 9900 would mean that 1% of visitors will be eligible for the experiment. This is only applicable for Web.

idinteger

The unique identifier for the Experiment

is_classicboolean

Whether or not the Experiment is a classic Experiment. If true, the Experiment is read-only

keystring

Unique string identifier for this Experiment within the Project. Only applicable for Full Stack and Mobile projects.

last_modifiedstring date-time

The last time the Experiment was modified

lateststring date-time

The last time the Experiment was paused (not present if the Experiment is still running). For campaign experiences, this field represents the last time the Campaign was paused.

multivariate_traffic_policy'full_factorial'

For Experiments of type multivariate, this specifies how the weights and statuses of combinations will be decided. In full_factorial mode, | combination weights are read-only, and are generated by multiplying together weights of section variations.

namestring

Name of the Experiment. Required for Web Experimentation. Optional for Web Personalization experiences and Full Stack experiments. Not applicable for Mobile Experiments.

page_idsinteger[]

A list of Page IDs used in the Experiment. url_targeting or page_ids, but not both.

project_idinteger required

The Project the Experiment is in

results_tokenstring

temporary token based on experiment id, used to access data platform services from other parts of the product

status'running' | 'paused' | 'archived' | 'campaign_paused' | 'concluded' | 'not_started'

Current state of the Experiment.<br> In Full Stack, this is the Experiment's state in the primary (production) environment.

traffic_allocationinteger

Percent of traffic allocated for the experiment, measured in basis points. 100 basis points = 1% traffic. For example, a value of 5500 would mean that 55% of visitors will be eligible for the experiment. This is only applicable for Full Stack.

type'a/b' | 'feature' | 'multivariate' | 'personalization' | 'multiarmed_bandit'

Indicates whether this is an a/b, multivariate, feature, or multiarmed_bandit test or an experience within a personalization campaign. Note that the default for this field is a/b. If another test type is desired, populate this field with the appropriate string (from one of the possible values).

Example response

{
  "audience_conditions": "[\"and\", {\"audience_id\": 7000}, {\"audience_id\":7001}]",
  "campaign_id": 2000,
  "changes": [
    {
      "dependencies": [
        "993fd09c-b64a-4c13-95a9-13b3ed2c454e",
        "95cf0144-fb63-431d-829b-193fe55ada18"
      ],
      "name": "Setting button text",
      "selector": "head",
      "value": "window.someGlobalFunction();"
    }
  ],
  "feature_id": 1000,
  "feature_name": "This is the user search feature",
  "holdback": 5000,
  "id": 3000,
  "key": "home_page_experiment",
  "name": "Blue Button Experiment",
  "project_id": 1000,
  "schedule": {
    "start_time": "2019-02-20T15:00",
    "stop_time": "2019-02-20T18:00",
    "time_zone": "America/New_York"
  },
  "traffic_allocation": 5000,
  "url_targeting": {
    "activation_code": "function callbackFn(activate, options) { activate(); }",
    "activation_type": "callback",
    "conditions": "[\"and\", {\"type\": \"url\", \"match_type\": \"substring\", \"value\": \"optimize\"}]",
    "edit_url": "https://www.optimizely.com",
    "key": "home_page",
    "page_id": 6700
  },
  "variations": [
    {
      "actions": [
        {
          "changes": [
            {
              "attributes": {
                "class": "intro",
                "href": "example.com",
                "html": "New Title",
                "src": "song.mp3",
                "style": "background-color:blue;",
                "text": "Some nice message"
              },
              "dependencies": [
                "ad1f6acb-78f2-4653-b955-913abd777e16",
                "ad20a6dd-2083-4964-8ed2-f0dc7baef687"
              ],
              "destination": "https://app.optimizely.com/",
              "destination_function": "https://app.optimizely.com/",
              "name": "Setting button text",
              "operator": "after",
              "selector": "a[href*=\"optimizely\"]",
              "value": "window.someGlobalFunction();"
            }
          ]
        }
      ],
      "key": "blue_button_variation",
      "name": "Blue Button"
    }
  ],
  "whitelist": [
    {
      "user_id": "user_1",
      "variation_id": 12345
    }
  ]
}