--- title: List Rules slug: feature-experimentation/api/list-rules docTags: createdAt: 2026-08-28T15:54:06.731Z --- { "id": "bU59lnDMfYkH8GwKgJLQn", "type": "api-oas-v2", "data": { "method": "GET", "url": "https://api.optimizely.com/flags/v1//projects/{project_id}/rules", "servers": [ { "url": "https://api.optimizely.com/flags/v1//projects/{project_id}/rules" } ], "name": "List Rules", "description": "

Get a list of Rules within a Project

\n

You can use query parameters to filter/sort the response.

", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "project_id", "type": "integer", "example": 12345, "description": "The project identifier" } ], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" } ], "queryParameters": [ { "kind": "optional", "name": "per_page", "type": "integer", "description": "The max number of items to include per page or results.", "format": "int64" }, { "kind": "optional", "name": "page_token", "type": "string", "description": "

Pagination page token. Implements prev, next, last, first

" }, { "kind": "optional", "name": "page_window", "type": "integer", "description": "

Number of previous and next page links to supply for the request (defaults to 1).

" }, { "kind": "optional", "name": "rule_types", "type": "string", "description": "

Filter the rules by rule type. A rule type can be A/B test, MAB etc.,

" }, { "kind": "optional", "name": "environments", "type": "string", "description": "

Filter the Rules by Environment. An Environment can be development, production etc.,

" }, { "kind": "optional", "name": "archived", "type": "boolean", "description": "

Filter the Environments by archived. An Environment can be either archived (archived=true) or unarchived (archived=false)

" }, { "kind": "optional", "name": "sort", "type": "array", "description": "Sort the Environments based on the attributes from left to right.\n", "schema": [], "itemType": "string", "customType": "string[]" } ], "bodyDataParameters": [], "formDataParameters": [], "oAuthParameters": [ { "id": "apiKey", "name": "apiKey", "kind": "optional", "type": "http", "scheme": "bearer" }, { "id": "OAuth2", "name": "OAuth2", "kind": "optional", "type": "oauth2", "description": "Write applications that authenticate with the REST API via OAuth 2.0.", "oauth2Flows": { "authorizationCode": { "authorizationUrl": "https://app.optimizely.com/oauth2/authorize", "tokenUrl": "https://app.optimizely.com/oauth2/token", "scopes": { "all": "Grants all access" } } }, "requiredScopes": [ "read", "write" ] } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "

Successful retrieval of a page of rules.

\n

The response includes RESTful JSON (https://restfuljson.org/) styled links and pagination metadata.\nObjects in this API MAY include a url property for a link to itself and MAY append _url to properties for related links.\nIf a link is not present in the response, it indicates a user is not authorized to access the related resource.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "Rules", "schema": [ { "name": "count", "kind": "required", "type": "integer", "description": "Number of Rules on the current page.", "example": 2 }, { "name": "items", "kind": "required", "type": "array", "description": "

Configuration which contains audiences, metrics and variations.

", "modelRef": "#/components/schemas/Rule", "customType": "Rule[]", "schema": [ { "name": "allow_list", "kind": "optional", "type": "map", "description": "User and Variation to force in the experiment", "example": "", "customType": "map", "schema": [] }, { "name": "archived", "kind": "optional", "type": "boolean", "description": "Indicates if the rule is archived or not.", "default": false }, { "name": "audience_conditions", "kind": "optional", "type": "array", "description": "

The audiences that should see this rule. 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.

", "example": "[\"[\"or\",{\"audience_id\":5340810295}]\"]", "itemType": "object", "customType": "object[]", "itemExample": "[\"or\",{\"audience_id\":5340810295}]", "itemDefault": "" }, { "name": "baseline_variation_id", "kind": "optional", "type": "integer", "nullable": true, "description": "

The id of the baseline variation, the original version of an experiment(e.g. control group) against which variations are compared.

" }, { "name": "comment", "kind": "optional", "type": "string", "description": "comment on conclusion of rule." }, { "name": "created_time", "kind": "optional", "type": "string", "readOnly": true, "description": "Timestamp when the Rule is created", "example": "2019-05-08T00:00:00.000Z", "format": "date-time" }, { "name": "custom_fields", "kind": "optional", "type": "map", "nullable": true, "description": "

Custom field values for this rule, keyed by custom field key.

", "example": "", "customType": "map", "schema": [] }, { "name": "deployed_td_rule_audience_conditions", "kind": "optional", "type": "array", "description": "The audiences that should see this deployed Targeted delivery rule.", "example": "[\"[\"or\",{\"audience_id\":5340810295}]\"]", "itemType": "object", "customType": "object[]", "itemExample": "[\"or\",{\"audience_id\":5340810295}]", "itemDefault": "" }, { "name": "deployed_td_rule_key", "kind": "optional", "type": "string", "description": "

deployed_td_rule_key on conclusion of rule.

" }, { "name": "deployed_td_rule_percentage_included", "kind": "optional", "type": "integer", "description": "

The percentage of the designated audiences that should get the new targeted delevery rule, measured in basis points. 100 basis points = 1% traffic

", "default": 0, "minimum": 0, "maximum": 10000 }, { "name": "deployed_variation_key", "kind": "optional", "type": "string", "description": "

deployed_variation_key on conclusion of rule.

" }, { "name": "description", "kind": "optional", "type": "string", "description": "Additional context of the Rule", "example": "This rule is used for delivery an experience to paid users" }, { "name": "distribution_mode", "kind": "optional", "type": "string", "nullable": true, "description": "

Type of rule distribution. Only a/b experiment can show distribution_mode field in the response

", "enum": [ "manual", "stats_accelerator" ] }, { "name": "enabled", "kind": "optional", "type": "boolean", "description": "Indicates if the rule is enabled or not in an environment.", "default": true }, { "name": "environment_key", "kind": "optional", "type": "string", "readOnly": true, "description": "

User-facing Environment identifier

" }, { "name": "environment_name", "kind": "optional", "type": "string", "readOnly": true, "description": "The name of the Environment" }, { "name": "fetch_results_ui_url", "kind": "optional", "type": "object", "readOnly": true, "description": "A url to be used to find a particular Results page. This field is optional and returned only if rule has results", "complexType": "allOf", "complexItems": [ { "name": "UrlValue", "description": "", "modelRef": "#/components/schemas/UrlValue", "schema": [] } ], "schema": [] }, { "name": "flag_key", "kind": "optional", "type": "string", "readOnly": true, "description": "

User-facing Unique identifier of the Flag.

" }, { "name": "flag_name", "kind": "optional", "type": "string", "readOnly": true, "description": "The name of the Flag" }, { "name": "group_id", "kind": "optional", "type": "string", "description": "Group id" }, { "name": "group_remaining_traffic_allocation", "kind": "optional", "type": "integer", "readOnly": true, "description": "Total remaining traffic allocation of the mutual exclusion group that this rule is in. This field is returned only if rule is has mutex group and user has mutex permissions" }, { "name": "group_rule", "kind": "optional", "type": "object", "description": "The Group information of this rule belongs to. This field is returned only if rule is has mutex group and user has mutex permissions", "example": "{\"id\":73915,\"name\":\"My Group\",\"traffic_allocation\":5000}", "modelRef": "#/components/schemas/RuleGroupRule", "customType": "RuleGroupRule", "schema": [ { "name": "group_id", "kind": "required", "type": "integer", "description": "Group id" }, { "name": "group_name", "kind": "optional", "type": "string", "readOnly": true, "description": "Name of the Group" }, { "name": "traffic_allocation", "kind": "optional", "type": "integer", "description": "The traffic allocation for the GroupRule", "minimum": 0, "maximum": 10000 } ] }, { "name": "hypothesis", "kind": "optional", "type": "string", "nullable": true, "description": "Experiment hypothesis text", "maxLength": 1000 }, { "name": "id", "kind": "optional", "type": "integer", "readOnly": true, "description": "", "example": 45633994 }, { "name": "key", "kind": "required", "type": "string", "description": "", "example": "paid_users" }, { "name": "layer_experiment_id", "kind": "optional", "type": "integer", "description": "", "example": 9000000013579 }, { "name": "layer_id", "kind": "optional", "type": "integer", "description": "", "example": 9000000013569 }, { "name": "metrics", "kind": "optional", "type": "array", "description": "List of metrics that are evaluated for the decision rules.", "modelRef": "#/components/schemas/Metric", "customType": "Metric[]", "schema": [ { "name": "aggregator", "kind": "required", "type": "string", "description": "

The aggregation function for the numerator of the metric. 'unique' measures the number of unique visitors/sessions that include the specified Event. 'count' measures the total number of occurrences of Event for the scope (visitor/session). 'sum' is the sum of the 'field' value

", "enum": [ "unique", "count", "sum", "ratio" ] }, { "name": "display_title", "kind": "optional", "type": "string", "description": "

An optional title for the unique metric configuration. If not provided, the event name will be used.

" }, { "name": "display_unit", "kind": "optional", "type": "string", "description": "An optional name for the unit of the unique metric configuration." }, { "name": "event_id", "kind": "optional", "type": "integer", "description": "

The ID for the Event to select data from. Omitted for global metrics that are not relative to a specific Event, i.e. \"overall revenue\"

", "example": 32334454244, "format": "int64" }, { "name": "event_properties", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "filter", "kind": "optional", "type": "object", "description": "", "example": "", "schema": [ { "name": "combine_operator", "kind": "optional", "type": "string", "description": "", "enum": [ "or", "and" ] }, { "name": "conditions", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/EventPropertyCondition", "customType": "EventPropertyCondition[]", "schema": [ { "name": "name", "kind": "required", "type": "string", "description": "" }, { "name": "operator", "kind": "required", "type": "string", "description": "", "enum": [ "equal_to", "not_equal_to", "greater_than", "greater_than_or_equal_to", "less_than", "less_than_or_equal_to", "contains", "does_not_contain" ] }, { "name": "type", "kind": "required", "type": "string", "description": "", "enum": [ "string", "number", "boolean" ] }, { "name": "value", "kind": "required", "type": "string", "description": "" } ] } ] } ] }, { "name": "event_type", "kind": "optional", "type": "string", "description": "" }, { "name": "field", "kind": "optional", "type": "string", "nullable": true, "description": "

The field to aggregate for the numerator of the metric. Required when 'aggregator' = 'sum', otherwise omitted

", "enum": [ "revenue", "value" ] }, { "name": "id", "kind": "optional", "type": "string", "description": "A unique identifier for the metric configuration." }, { "name": "metrics", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/SubMetric", "customType": "SubMetric[]", "schema": [ { "name": "aggregator", "kind": "optional", "type": "string", "description": "" }, { "name": "display_title", "kind": "optional", "type": "string", "nullable": true, "description": "" }, { "name": "event_id", "kind": "optional", "type": "integer", "description": "" }, { "name": "event_type", "kind": "optional", "type": "string", "description": "" }, { "name": "field", "kind": "optional", "type": "string", "nullable": true, "description": "" }, { "name": "role", "kind": "optional", "type": "string", "description": "", "enum": [ "numerator", "denominator" ] }, { "name": "scope", "kind": "optional", "type": "string", "description": "" } ] }, { "name": "project_id", "kind": "optional", "type": "integer", "description": "A unique identifier for the project associated with the metric." }, { "name": "scope", "kind": "optional", "type": "string", "description": "

Specifies how Events should be grouped together. Can also be thought of as the denonimator of the metric. 'session' divides by the number of sessions. \"Influenced sessions\", or sessions that do not contain a decision Event but carry a decision from a previous session are not included in counts for numerator or denominator. 'visitor' divides by the number of visitors. 'event' divides by the total occurrences (impressions) of the specified Event

", "enum": [ "session", "visitor", "event" ] }, { "name": "visibility", "kind": "optional", "type": "string", "description": "The visibility of the metric.", "enum": [ "account", "experiment", "project" ] }, { "name": "winning_direction", "kind": "required", "type": "string", "description": "The winning direction of this metric", "enum": [ "increasing", "decreasing" ] } ] }, { "name": "name", "kind": "required", "type": "string", "description": "", "example": "Paid Users" }, { "name": "outcome", "kind": "optional", "type": "string", "description": "outcome of rule.", "enum": [ "positive", "negative", "inconclusive" ] }, { "name": "percentage_included", "kind": "optional", "type": "integer", "description": "

The percentage of the designated audiences that should get the decision rule, measured in basis points. 100 basis points = 1% traffic

", "default": 0, "minimum": 0, "maximum": 10000 }, { "name": "status", "kind": "optional", "type": "string", "description": "status of rule. Status will change to 'Running' when Ruleset is 'Running'.", "enum": [ "draft", "running", "paused", "concluded" ] }, { "name": "test_plan_name", "kind": "optional", "type": "string", "nullable": true, "description": "Test plan reference text or uploaded file name", "maxLength": 255 }, { "name": "test_plan_type", "kind": "optional", "type": "string", "nullable": true, "description": "Type of test plan attachment", "enum": [ "url", "file" ] }, { "name": "test_plan_url", "kind": "optional", "type": "string", "nullable": true, "description": "

Test plan URL (external) or backend proxy path (file)

", "maxLength": 2000 }, { "name": "type", "kind": "required", "type": "string", "description": "Type of rule.", "enum": [ "targeted_delivery", "a/b", "multi_armed_bandit", "feature_rollout" ] }, { "name": "updated_time", "kind": "optional", "type": "string", "readOnly": true, "description": "Timestamp when the Rule is updated", "example": "2019-05-08T00:00:00.000Z", "format": "date-time" }, { "name": "urn", "kind": "optional", "type": "string", "readOnly": true, "description": "The URN for the Rule", "example": "rules.flags.optimizely.com::45633910" }, { "name": "variations", "kind": "optional", "type": "map", "description": "Map of variations by variation key.", "example": "", "customType": "map", "schema": [] } ] }, { "name": "page", "kind": "required", "type": "integer", "description": "

Number of the current page. 1-index based.

", "example": 5 }, { "name": "total_count", "kind": "required", "type": "integer", "description": "Total number of Rules for this series.", "example": 20 }, { "name": "total_pages", "kind": "required", "type": "integer", "description": "Total number of pages for this series.", "example": 10 }, { "name": "url", "kind": "required", "type": "object", "description": "Link to self", "complexType": "allOf", "complexItems": [ { "name": "UrlValue", "description": "", "modelRef": "#/components/schemas/UrlValue", "schema": [] } ], "schema": [] } ], "modelRef": "#/components/schemas/Rules", "isExpanded": true } ] }, { "statusCode": "400", "description": "Malformed requests and invalid parameter names and types", "jsonExample": "", "isExpanded": true }, { "statusCode": "401", "description": "Invalid credentials", "jsonExample": "", "isExpanded": true }, { "statusCode": "403", "description": "Do not have permission to perform the operation", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "ZK4lZmoy97dI6kqakzRad", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url https://api.optimizely.com/flags/v1//projects/{project_id}/rules \\\n --header 'accept: application/json'" }, { "id": "B9p_vpfrU143c5nPeRAvb", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api.optimizely.com/flags/v1//projects/{project_id}/rules\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "7s9Y-3WKSGM0U7O8x_C7U", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.optimizely.com/flags/v1//projects/{project_id}/rules\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "Dku6JhRTCjiofv0s63tGn", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.optimizely.com/flags/v1//projects/{project_id}/rules\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "ZK4lZmoy97dI6kqakzRad" }, "results": { "languages": [ { "id": "response-0-200", "language": "200", "code": "// Successful retrieval of a page of rules.\nThe response includes RESTful JSON (https://restfuljson.org/) styled links and pagination metadata.\nObjects in this API MAY include a url property for a link to itself and MAY append _url to properties for related links.\nIf a link is not present in the response, it indicates a user is not authorized to access the related resource.\n{\n \"count\": 2,\n \"items\": [\n {\n \"allow_list\": \"\",\n \"archived\": false,\n \"audience_conditions\": [\n {}\n ],\n \"baseline_variation_id\": 0,\n \"comment\": \"\",\n \"created_time\": \"2019-05-08T00:00:00.000Z\",\n \"custom_fields\": \"\",\n \"deployed_td_rule_audience_conditions\": [\n {}\n ],\n \"deployed_td_rule_key\": \"\",\n \"deployed_td_rule_percentage_included\": 0,\n \"deployed_variation_key\": \"\",\n \"description\": \"This rule is used for delivery an experience to paid users\",\n \"distribution_mode\": \"\",\n \"enabled\": false,\n \"environment_key\": \"\",\n \"environment_name\": \"\",\n \"fetch_results_ui_url\": {},\n \"flag_key\": \"\",\n \"flag_name\": \"\",\n \"group_id\": \"\",\n \"group_remaining_traffic_allocation\": 0,\n \"group_rule\": {\n \"group_id\": 0,\n \"group_name\": \"\",\n \"traffic_allocation\": 0\n },\n \"hypothesis\": \"\",\n \"id\": 45633994,\n \"key\": \"paid_users\",\n \"layer_experiment_id\": 9000000013579,\n \"layer_id\": 9000000013569,\n \"metrics\": [\n {\n \"aggregator\": \"\",\n \"display_title\": \"\",\n \"display_unit\": \"\",\n \"event_id\": 32334454244,\n \"event_properties\": {\n \"filter\": {\n \"combine_operator\": \"\",\n \"conditions\": [\n {\n \"name\": \"\",\n \"operator\": \"\",\n \"type\": \"\",\n \"value\": \"\"\n }\n ]\n }\n },\n \"event_type\": \"\",\n \"field\": \"\",\n \"id\": \"\",\n \"metrics\": [\n {\n \"aggregator\": \"\",\n \"display_title\": \"\",\n \"event_id\": 0,\n \"event_type\": \"\",\n \"field\": \"\",\n \"role\": \"\",\n \"scope\": \"\"\n }\n ],\n \"project_id\": 0,\n \"scope\": \"\",\n \"visibility\": \"\",\n \"winning_direction\": \"\"\n }\n ],\n \"name\": \"Paid Users\",\n \"outcome\": \"\",\n \"percentage_included\": 0,\n \"status\": \"\",\n \"test_plan_name\": \"\",\n \"test_plan_type\": \"\",\n \"test_plan_url\": \"\",\n \"type\": \"\",\n \"updated_time\": \"2019-05-08T00:00:00.000Z\",\n \"urn\": \"rules.flags.optimizely.com::45633910\",\n \"variations\": \"\"\n }\n ],\n \"page\": 5,\n \"total_count\": 20,\n \"total_pages\": 10,\n \"url\": {}\n}" }, { "id": "response-1-400", "language": "400", "code": "// Malformed requests and invalid parameter names and types\n" }, { "id": "response-2-401", "language": "401", "code": "// Invalid credentials\n" }, { "id": "response-3-403", "language": "403", "code": "// Do not have permission to perform the operation\n" } ], "selectedLanguageId": "response-0-200" } }, "children": [ { "text": "" } ] }