Manage rules
14 min
Rules contain the experiment and targeting logic within a flag. Rules describe what variation the flag should deliver to a given user. A ruleset is the collection of rules associated with a flag.
With the Feature Experimentation REST API
See the Rulesets and Rules API endpoints for information on managing rules with the Feature Experimentation REST API.
For each cURL command, include your API key in the Authorization header as a Bearer token. See Generate tokens and use the REST APIsGenerate tokens and use the REST APIs for information.
Rulesets
Read rulesets
Use the Fetch the Ruleset for a Flag in an Environment API endpoint.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset
Example request
curl --request GET \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Example response
{
"url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
"update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
"disable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/disabled",
"rules": {
"landing_page_targeted_delivery": {
"key": "landing_page_targeted_delivery",
"name": "Targeted Delivery for the landing page",
"description": "",
"variations": {
"on": {
"key": "on",
"name": "On",
"percentage_included": 10000,
"variation_id": 1500954,
"id": 6669615
}
},
"baseline_variation_id": null,
"type": "targeted_delivery",
"id": 1598837,
"urn": "rules.flags.optimizely.com::1598837",
"archived": false,
"enabled": true,
"created_time": "2025-09-12T20:14:49.374112Z",
"updated_time": "2025-09-12T20:39:18.170572Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [],
"allow_list": {},
"layer_id": 9300001985290,
"layer_experiment_id": 9300002731002,
"status": "running"
}
},
"rule_priorities": [],
"id": 1881462,
"urn": "rulesets.flags.optimizely.com::1881462",
"archived": false,
"enabled": true,
"updated_time": "2025-09-12T20:39:18.170572Z",
"flag_key": "targeted-delivery-flag",
"environment_key": "development",
"environment_name": "Development",
"environment_id": ENVIRONMENT_ID,
"default_variation_key": "off",
"default_variation_name": "Off",
"revision": 6,
"status": "running",
"role": "admin",
"approval_settings": {}
}Update rulesets
Use the Update the Ruleset for a Flag in an Environment API endpoint.
For PATCH requests, first Fetch the Ruleset for a Flag in an Environment, merge only the fields you need to change, and then send the PATCH. This helps prevent overwriting existing settings you did not intend to modify.
Options include: add, remove, replace, move, copy, and test.
Endpoint – PATCH https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset
You must disable your rule before removing it.
Example request
curl --request PATCH \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN' \
--header 'content-type: application/json-patch+json' \
--data '
[
{
"op": "replace",
"path": "/rules/landing_page_targeted_delivery/enabled",
"value": true
}
]
'Example response
{
"url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
"update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
"disable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/disabled",
"rules": {
"landing_page_targeted_delivery": {
"key": "landing_page_targeted_delivery",
"name": "Targeted Delivery for the landing page",
"description": "",
"variations": {
"on": {
"key": "on",
"name": "On",
"percentage_included": 10000,
"variation_id": 1500954,
"id": 6669615
}
},
"baseline_variation_id": null,
"type": "targeted_delivery",
"id": 1598837,
"urn": "rules.flags.optimizely.com::1598837",
"archived": false,
"enabled": true,
"created_time": "2025-09-12T20:14:49.374112Z",
"updated_time": "2025-09-12T20:26:05.310167Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [],
"allow_list": {},
"layer_id": 9300001985290,
"layer_experiment_id": 9300002731002,
"status": "running"
}
},
"rule_priorities": [
"landing_page_targeted_delivery"
],
"id": 1881462,
"urn": "rulesets.flags.optimizely.com::1881462",
"archived": false,
"enabled": true,
"updated_time": "2025-09-12T20:26:05.381855Z",
"flag_key": "targeted-delivery-flag",
"environment_key": "development",
"environment_name": "Development",
"environment_id": ENVIRONMENT_ID,
"default_variation_key": "off",
"default_variation_name": "Off",
"revision": 4,
"status": "running",
"role": "admin"
}Disable rulesets
Use the Disable the Ruleset for a Flag in an Environment API endpoint.
Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/disabled
Example request
curl --request POST \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/disabled \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Example response
{
"url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
"update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
"enable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/enabled",
"rules": {
"landing_page_targeted_delivery": {
"key": "landing_page_targeted_delivery",
"name": "Targeted Delivery for the landing page",
"description": "",
"variations": {
"on": {
"key": "on",
"name": "On",
"percentage_included": 10000,
"variation_id": 1500954,
"id": 6669615
}
},
"baseline_variation_id": null,
"type": "targeted_delivery",
"id": 1598837,
"urn": "rules.flags.optimizely.com::1598837",
"archived": false,
"enabled": true,
"created_time": "2025-09-12T20:14:49.374112Z",
"updated_time": "2025-09-12T20:57:04.728173Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [],
"allow_list": {},
"layer_id": 9300001985290,
"layer_experiment_id": 9300002731002,
"status": "running"
}
},
"rule_priorities": [],
"id": 1881462,
"urn": "rulesets.flags.optimizely.com::1881462",
"archived": false,
"enabled": false,
"updated_time": "2025-09-12T20:57:04.728173Z",
"flag_key": "targeted-delivery-flag",
"environment_key": "development",
"environment_name": "Development",
"environment_id": ENVIRONMENT_ID,
"default_variation_key": "off",
"default_variation_name": "Off",
"revision": 7,
"status": "paused",
"role": "admin"
}Enable rulesets
Use the Enable the Ruleset for a Flag in an Environment API endpoint.
Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/enabled
Example request
curl --request POST \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/enabled \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Example response
{
"url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
"update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
"disable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/disabled",
"rules": {
"landing_page_targeted_delivery": {
"key": "landing_page_targeted_delivery",
"name": "Targeted Delivery for the landing page",
"description": "",
"variations": {
"on": {
"key": "on",
"name": "On",
"percentage_included": 10000,
"variation_id": 1500954,
"id": 6669615
}
},
"baseline_variation_id": null,
"type": "targeted_delivery",
"id": 1598837,
"urn": "rules.flags.optimizely.com::1598837",
"archived": false,
"enabled": true,
"created_time": "2025-09-12T20:14:49.374112Z",
"updated_time": "2025-09-12T20:58:41.725828Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [],
"allow_list": {},
"layer_id": 9300001985290,
"layer_experiment_id": 9300002731002,
"status": "running"
}
},
"rule_priorities": [],
"id": 1881462,
"urn": "rulesets.flags.optimizely.com::1881462",
"archived": false,
"enabled": true,
"updated_time": "2025-09-12T20:58:41.725828Z",
"flag_key": "targeted-delivery-flag",
"environment_key": "development",
"environment_name": "Development",
"environment_id": ENVIRONMENT_ID,
"default_variation_key": "off",
"default_variation_name": "Off",
"revision": 8,
"status": "running",
"role": "admin"
}Rules
List rules in a project
Use the List Rules API endpoint.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules
Example request
curl --request GET \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Example response
{
"count": 6,
"total_count": 6,
"total_pages": 1,
"url": "/projects/PROJECT_ID/rules",
"page": 1,
"items": [
{
"key": "landing_page_targeted_delivery",
"name": "Targeted Delivery for the landing page",
"description": "",
"variations": {
"on": {
"key": "on",
"name": "On",
"percentage_included": 10000,
"variation_id": 1500954,
"id": 6669615
}
},
"baseline_variation_id": null,
"type": "targeted_delivery",
"id": 1598837,
"urn": "rules.flags.optimizely.com::1598837",
"archived": false,
"enabled": true,
"created_time": "2025-09-12T20:14:49.374112Z",
"updated_time": "2025-09-12T20:58:41.725828Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [],
"allow_list": {},
"group_remaining_traffic_allocation": 100,
"layer_id": 9300001985290,
"layer_experiment_id": 9300002731002,
"status": "running",
"project_id": PROJECT_ID,
"group_id": "",
"flag_key": "targeted-delivery-flag",
"flag_name": "Targeted-delivery-flag",
"flag_status": "unarchived",
"environment_key": "development",
"environment_name": "Development"
},
{
"key": "stock_message_test",
"name": "Stock Message Test",
"description": "",
"variations": {
"off": {
"key": "off",
"name": "Off",
"percentage_included": 5000,
"variation_id": 1500962,
"id": 6669660
},
"on": {
"key": "on",
"name": "On",
"percentage_included": 5000,
"variation_id": 1500963,
"id": 6669661
}
},
"baseline_variation_id": null,
"type": "a/b",
"distribution_mode": "manual",
"id": 1598853,
"urn": "rules.flags.optimizely.com::1598853",
"archived": false,
"enabled": false,
"created_time": "2025-09-12T20:39:20.565416Z",
"updated_time": "2025-09-12T20:39:20.554081Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [
{
"event_id": 5312230607028224,
"scope": "visitor",
"aggregator": "unique",
"winning_direction": "increasing",
"display_title": "add_to_cart",
"id": "46135e38-8e67-4656-826b-b3343d564f03",
"alias": "dca1a5a6b8ea8c1beca2648e739e306e5d6a9399b041cbee72594ce75ef84d0b",
"visibility": "experiment",
"project_id": PROJECT_ID,
"updated_at": "2025-09-12T20:39:21.758625965Z",
"account_id": ACCOUNT_ID
}
],
"allow_list": {},
"group_rule": {
"group_id": 0,
"traffic_allocation": 0
},
"group_remaining_traffic_allocation": 100,
"layer_id": 9300001985314,
"layer_experiment_id": 9300002731026,
"status": "draft",
"project_id": PROJECT_ID,
"group_id": "",
"flag_key": "a_b_test_flag",
"flag_name": "a_b_test_flag",
"flag_status": "unarchived",
"environment_key": "development",
"environment_name": "Development"
},
{
"key": "already-existing-a-b-test",
"name": "Already-exisiting-a-b-test",
"description": "",
"variations": {
"off": {
"key": "off",
"name": "Off",
"percentage_included": 5000,
"variation_id": 1500745,
"id": 6669306
},
"on": {
"key": "on",
"name": "On",
"percentage_included": 5000,
"variation_id": 1500746,
"id": 6669307
}
},
"baseline_variation_id": 1500745,
"type": "a/b",
"distribution_mode": "manual",
"id": 1598646,
"urn": "rules.flags.optimizely.com::1598646",
"archived": false,
"enabled": true,
"created_time": "2025-09-12T16:44:11.824135Z",
"updated_time": "2025-09-12T19:51:52.213225Z",
"audience_conditions": [
"or",
{
"audience_id": 5589361492754432
}
],
"audience_ids": [
5589361492754432
],
"percentage_included": 10000,
"metrics": [
{
"event_id": 5504179729334272,
"scope": "visitor",
"aggregator": "unique",
"winning_direction": "increasing",
"display_title": "PDP Page Views",
"id": "2f7cd919-c73b-4a99-81c7-daa69e1cc2a6",
"alias": "b20520c09877f956ad8a7ef7723139006f01174e69b253d1896c9d0a82ebe212",
"visibility": "account",
"updated_at": "2025-05-21T15:40:30.967744070Z",
"account_id": ACCOUNT_ID
}
],
"fetch_results_ui_url": "https://app.optimizely.com/v2/projects/PROJECT_ID/results/RESULTS_ID/experiments/EXPERIMENT_ID?baseline=BASELINE_VARIATION_ID",
"allow_list": {},
"group_rule": {
"group_id": 0,
"traffic_allocation": 0
},
"group_remaining_traffic_allocation": 100,
"layer_id": 9300001984917,
"layer_experiment_id": 9300002730629,
"status": "running",
"project_id": PROJECT_ID,
"group_id": "",
"flag_key": "doc-test-flag",
"flag_name": "Doc test flag",
"flag_status": "unarchived",
"environment_key": "development",
"environment_name": "Development"
},
{
"key": "mab_test",
"name": "Multi-armed Test",
"description": "",
"variations": {
"off": {
"key": "off",
"name": "Off",
"percentage_included": 3333,
"variation_id": 1500745,
"id": 6668479
},
"on": {
"key": "on",
"name": "On",
"percentage_included": 3333,
"variation_id": 1500746,
"id": 6668480
},
"on_hide_amounts": {
"key": "on_hide_amounts",
"name": "On Hide Amounts",
"percentage_included": 3334,
"variation_id": 1500757,
"id": 6668481
}
},
"baseline_variation_id": null,
"type": "multi_armed_bandit",
"id": 1598723,
"urn": "rules.flags.optimizely.com::1598723",
"archived": false,
"enabled": false,
"created_time": "2025-09-12T17:45:13.103056Z",
"updated_time": "2025-09-12T19:40:45.033536Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [
{
"event_id": 5504179729334272,
"scope": "visitor",
"aggregator": "unique",
"winning_direction": "increasing",
"display_title": "add_to_cart",
"id": "ca56e5d6-b1ad-4ef2-94b6-7fb176fe20ac",
"alias": "9ea078c4bef9300012b0f5452289d569f0b95bfa230168d9734424952199933a",
"visibility": "experiment",
"project_id": PROJECT_ID,
"updated_at": "2025-09-12T17:45:14.341649449Z",
"account_id": ACCOUNT_ID
}
],
"allow_list": {},
"group_rule": {
"group_id": 0,
"traffic_allocation": 0
},
"group_remaining_traffic_allocation": 100,
"layer_id": 9300001985070,
"layer_experiment_id": 9300002730782,
"status": "draft",
"project_id": PROJECT_ID,
"group_id": "",
"flag_key": "doc-test-flag",
"flag_name": "Doc test flag",
"flag_status": "unarchived",
"environment_key": "development",
"environment_name": "Development"
},
{
"key": "experiment",
"name": "experiment",
"description": "",
"variations": {
"off": {
"key": "off",
"name": "Off",
"percentage_included": 5000,
"variation_id": 1223804,
"id": 5403098
},
"on": {
"key": "on",
"name": "On",
"percentage_included": 5000,
"variation_id": 1313957,
"id": 5403099
}
},
"baseline_variation_id": null,
"type": "a/b",
"distribution_mode": "manual",
"id": 1428193,
"urn": "rules.flags.optimizely.com::1428193",
"archived": false,
"enabled": true,
"created_time": "2025-04-29T21:10:01.059880Z",
"updated_time": "2025-04-29T21:10:26.370340Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [
{
"event_id": 4987522074279936,
"scope": "visitor",
"aggregator": "unique",
"winning_direction": "increasing",
"display_title": "purchase",
"id": "e4e94605-f780-4037-aaba-02e944732158",
"alias": "9548e56d6c2f9a32a4152c8b33f946b6538460c53ec01da0bb54b39953443628",
"visibility": "project",
"project_id": PROJECT_ID,
"updated_at": "2025-04-29T21:08:59.655557295Z",
"description": "Purchase metric from the Python SDK quickstart.",
"account_id": ACCOUNT_ID
}
],
"fetch_results_ui_url": "https://app.optimizely.com/v2/projects/PROJECT_ID/results/RESULTS_ID/experiments/EXPERIMENT_ID",
"allow_list": {},
"group_rule": {
"group_id": 0,
"traffic_allocation": 0
},
"group_remaining_traffic_allocation": 100,
"layer_id": 9300001661503,
"layer_experiment_id": 9300002382064,
"status": "running",
"project_id": PROJECT_ID,
"group_id": "",
"flag_key": "product_sort",
"flag_name": "Product sort",
"flag_status": "unarchived",
"environment_key": "production",
"environment_name": "Production"
},
{
"key": "best_sort_method",
"name": "Best sort method",
"description": "",
"variations": {
"off": {
"key": "off",
"name": "Off",
"percentage_included": 10000,
"variation_id": 1223804,
"id": 5112052
}
},
"baseline_variation_id": null,
"type": "a/b",
"distribution_mode": "manual",
"id": 1291104,
"urn": "rules.flags.optimizely.com::1291104",
"archived": false,
"enabled": false,
"created_time": "2025-04-14T21:44:42.781693Z",
"updated_time": "2025-04-14T21:49:39.008847Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [
{
"event_id": 10884603042,
"scope": "visitor",
"aggregator": "sum",
"winning_direction": "increasing",
"display_title": "Cross-project-metric",
"id": "d790121e-de7f-41f0-a973-13e553f9c31c",
"alias": "6a9b1b79a56a090b1e9e486712250c2d5511f388dedbf9c105a43a2979f66af3",
"visibility": "account",
"updated_at": "2025-04-17T23:42:38.214532319Z",
"description": "A metric available across all projects. ",
"account_id": ACCOUNT_ID
}
],
"allow_list": {},
"group_rule": {
"group_id": 0,
"traffic_allocation": 0
},
"group_remaining_traffic_allocation": 100,
"layer_id": 9300001587905,
"layer_experiment_id": 9300002212100,
"status": "draft",
"project_id": PROJECT_ID,
"group_id": "",
"flag_key": "product_sort",
"flag_name": "Product sort",
"flag_status": "unarchived",
"environment_key": "development",
"environment_name": "Development"
}
],
"last_url": "/projects/PROJECT_ID/rules",
"first_url": "/projects/PROJECT_ID/rules"
}See the List Rules API reference documentation for optional query parameters.
Fetch the rules for a ruleset by Feature Experimentation environment
Use the Fetch the Rule for a Ruleset in an Environment API endpoint.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/rules/RULE_KEY
Example request
curl --request GET \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/rules/landing_page_targeted_delivery \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Example response
{
"key": "landing_page_targeted_delivery",
"name": "Targeted Delivery for the landing page",
"description": "",
"variations": {
"on": {
"key": "on",
"name": "On",
"percentage_included": 10000,
"variation_id": 1500954,
"id": 6669615
}
},
"baseline_variation_id": null,
"type": "targeted_delivery",
"id": 1598837,
"urn": "rules.flags.optimizely.com::1598837",
"archived": false,
"enabled": true,
"created_time": "2025-09-12T20:14:49.374112Z",
"updated_time": "2025-09-12T20:58:41.725828Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [],
"allow_list": {},
"layer_id": 9300001985290,
"layer_experiment_id": 9300002731002,
"status": "running",
"experiment_id": 9300002731002,
"environment_key": "development",
"flag_key": "targeted-delivery-flag",
"environment_name": "Development",
"flag_name": "Targeted-delivery-flag"
}Read a rule for a specific experiment ID
Use the Fetch a Rule for a specific experiment_id API endpoint.
Endpoint – GET https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules/EXPERIMENT_ID
Example request
curl --request GET \
--url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/rules/EXPERIMENT_ID \
--header 'accept: application/json' \
--header 'authorization: Bearer TOKEN'Example response
{
"key": "stock_message_test",
"name": "Stock Message Test",
"description": "",
"variations": {
"off": {
"key": "off",
"name": "Off",
"percentage_included": 5000,
"variation_id": 1500962,
"id": 6669660
},
"on": {
"key": "on",
"name": "On",
"percentage_included": 5000,
"variation_id": 1500963,
"id": 6669661
}
},
"baseline_variation_id": null,
"type": "a/b",
"distribution_mode": "manual",
"id": 1598853,
"urn": "rules.flags.optimizely.com::1598853",
"archived": false,
"enabled": false,
"created_time": "2025-09-12T20:39:20.565416Z",
"updated_time": "2025-09-12T20:39:20.554081Z",
"audience_conditions": [],
"audience_ids": [],
"percentage_included": 10000,
"metrics": [
{
"event_id": 5312230607028224,
"event_type": "custom",
"scope": "visitor",
"aggregator": "unique",
"winning_direction": "increasing",
"display_title": "add_to_cart",
"alias": "dca1a5a6b8ea8c1beca2648e739e306e5d6a9399b041cbee72594ce75ef84d0b",
"id": "46135e38-8e67-4656-826b-b3343d564f03",
"project_id": PROJECT_ID,
"visibility": "experiment",
"updated_at": "2025-09-12T20:39:21.758625965Z",
"account_id": ACCOUNT_ID,
"event_scoped": false
}
],
"allow_list": {},
"group_rule": {
"group_id": 0,
"traffic_allocation": 0
},
"group_remaining_traffic_allocation": 100,
"layer_id": 9300001985314,
"layer_experiment_id": 9300002731026,
"status": "draft",
"experiment_id": 9300002731026,
"environment_key": "development",
"flag_key": "a_b_test_flag",
"environment_name": "Development",
"flag_name": "a_b_test_flag"
}With the Feature Experimentation UI
See Manage rules in the user documentation.