---
title: List Flags
slug: feature-experimentation/api/list-flags
docTags: 
createdAt: 2026-08-28T15:54:06.731Z
---

{
  "id": "hzGRTQJdVAN7e7COPW4dY",
  "type": "api-oas-v2",
  "data": {
    "method": "GET",
    "url": "https://api.optimizely.com/flags/v1//projects/{project_id}/flags",
    "servers": [
      {
        "url": "https://api.optimizely.com/flags/v1//projects/{project_id}/flags"
      }
    ],
    "name": "List Flags",
    "description": "<p>Get a list of Flags within a Project</p>\n<p>You can use query parameters to filter/sort the response.</p>",
    "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<int64>",
          "description": "The max number of items to include per page or results.",
          "format": "int64"
        },
        {
          "kind": "optional",
          "name": "page_number",
          "type": "integer<int64>",
          "description": "<p>Bypass page_token to jump to specific page</p>",
          "format": "int64"
        },
        {
          "kind": "optional",
          "name": "page_token",
          "type": "string",
          "description": "<p>Pagination page token. Implements prev, next, last, first</p>"
        },
        {
          "kind": "optional",
          "name": "page_window",
          "type": "integer",
          "description": "<p>Number of previous and next page links to supply for the request (defaults to 1).</p>"
        },
        {
          "kind": "optional",
          "name": "sort",
          "type": "array",
          "description": "Sort the Flags based on the attributes from left to right.\n",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        },
        {
          "kind": "optional",
          "name": "archived",
          "type": "boolean",
          "description": "<p>Filter the Flags by archived. A Flag can be either archived (archived=true) or unarchived (archived=false)</p>"
        },
        {
          "kind": "optional",
          "name": "enabled",
          "type": "boolean",
          "description": "<p>Filter the Flags by enabled. A Flag can be either enabled (enabled=true) or disabled (enabled=false)</p>"
        },
        {
          "kind": "optional",
          "name": "flag_status",
          "type": "array",
          "example": "[\"live\",\"paused\"]",
          "description": "<p>Filter the Flags by lifecycle status. Allowed values: draft, testing, live, paused, stale, archived.\nValues may be prefixed with <code>!</code> to exclude that status.</p>\n<ul>\n<li>For matching one: <code>flag_status=live</code></li>\n<li>For matching multiple (repeated params): <code>flag_status=live&#x26;flag_status=paused</code></li>\n<li>For excluding: <code>flag_status=!draft&#x26;flag_status=!archived</code></li>\n</ul>",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        },
        {
          "kind": "optional",
          "name": "rule_status",
          "type": "array",
          "example": "[\"draft\",\"!concluded\"]",
          "description": "<p>Filter the Flags by Rule Status. Supports matching one, multiple, or excluding multiple values.</p>\n<ul>\n<li>For matching one: <code>rule_status=value</code></li>\n<li>For matching multiple: <code>rule_status=value1,value2</code></li>\n<li>For excluding multiple: <code>rule_status=!value1,!value2</code></li>\n</ul>",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        },
        {
          "kind": "optional",
          "name": "environment_status",
          "type": "array",
          "example": "[\"draft\",\"!concluded\"]",
          "description": "<p>Filter the Flags by Environment Status. Supports matching one, multiple, or excluding multiple values.</p>\n<ul>\n<li>For matching one: <code>environment_status=value</code></li>\n<li>For matching multiple: <code>environment_status=value1,value2</code></li>\n<li>For excluding multiple: <code>environment_status=!value1,!value2</code></li>\n</ul>",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        },
        {
          "kind": "optional",
          "name": "environment_type",
          "type": "array",
          "description": "<p>Filter the Flags by the environment_type</p>",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        },
        {
          "kind": "optional",
          "name": "environment",
          "type": "array",
          "description": "Filter the Flags by the environment\n",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        },
        {
          "kind": "optional",
          "name": "rule_type",
          "type": "array",
          "description": "Filter the Flags by the rule type.",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        },
        {
          "kind": "optional",
          "name": "query",
          "type": "string",
          "description": "<p>Filter the Flags by name, key, or\ndescription substring</p>"
        },
        {
          "kind": "optional",
          "name": "key_list",
          "type": "array",
          "description": "Filter the Flags by multiple keys\n",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        },
        {
          "kind": "optional",
          "name": "owner_user_id",
          "type": "array",
          "description": "<p>Filter Flags by owner user ID(s). Accepts single or multiple values.\nValues may be prefixed with <code>!</code> to exclude that owner.</p>\n<ul>\n<li>For matching one: <code>owner_user_id=user_1</code></li>\n<li>For matching multiple (repeated params): <code>owner_user_id=user_1&#x26;owner_user_id=user_2</code></li>\n<li>For matching multiple (comma-separated): <code>owner_user_id=user_1,user_2</code></li>\n<li>For excluding: <code>owner_user_id=!user_1&#x26;owner_user_id=!user_2</code></li>\n<li>For flags with no owner (NULL): <code>owner_user_id=</code></li>\n<li>For flags with owner OR no owner: <code>owner_user_id=user_1&#x26;owner_user_id=</code></li>\n<li>For excluding flags with no owner: <code>owner_user_id=!</code></li>\n</ul>",
          "schema": [],
          "itemType": "string",
          "customType": "string[]"
        },
        {
          "kind": "optional",
          "name": "team_ids",
          "type": "array",
          "description": "<p>Filter Flags by team ID(s). Returns flags that have ANY of the specified team IDs.\nValues may be prefixed with <code>!</code> to exclude flags with those team IDs.</p>\n<ul>\n<li>For matching one: <code>team_ids=100</code></li>\n<li>For matching multiple (repeated params): <code>team_ids=100&#x26;team_ids=200</code></li>\n<li>For matching multiple (comma-separated): <code>team_ids=100,200</code></li>\n<li>For excluding: <code>team_ids=!100&#x26;team_ids=!200</code></li>\n<li>For flags with no teams (NULL/empty array): <code>team_ids=</code></li>\n<li>For flags with specific team OR no teams: <code>team_ids=100&#x26;team_ids=</code></li>\n<li>For excluding flags with no teams: <code>team_ids=!</code></li>\n</ul>",
          "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": "<p>Successful retrieval of a page of Flags.</p>\n<p>The response includes RESTful JSON (<a href=\"https://restfuljson.org/\" target=\"_blank\">https://restfuljson.org/</a>) 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.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "",
            "customType": "Flags",
            "schema": [
              {
                "name": "count",
                "kind": "required",
                "type": "integer",
                "description": "Number of Flags on the current page.",
                "example": 2
              },
              {
                "name": "create_url",
                "kind": "optional",
                "type": "object",
                "description": "",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "UrlValue",
                    "description": "",
                    "modelRef": "#/components/schemas/UrlValue",
                    "schema": []
                  }
                ],
                "schema": []
              },
              {
                "name": "fetch_flag_url",
                "kind": "optional",
                "type": "object",
                "description": "A url template to be used to find a particular Flag.\n",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "UrlValue",
                    "description": "",
                    "modelRef": "#/components/schemas/UrlValue",
                    "schema": []
                  }
                ],
                "schema": []
              },
              {
                "name": "filter_url",
                "kind": "optional",
                "type": "object",
                "description": "<p>Url template like '.../{?filter}'</p>",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "UrlValue",
                    "description": "",
                    "modelRef": "#/components/schemas/UrlValue",
                    "schema": []
                  }
                ],
                "schema": []
              },
              {
                "name": "first_url",
                "kind": "required",
                "type": "object",
                "description": "Link to first page of Flags in a series.",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "UrlValue",
                    "description": "",
                    "modelRef": "#/components/schemas/UrlValue",
                    "schema": []
                  }
                ],
                "schema": []
              },
              {
                "name": "items",
                "kind": "required",
                "type": "array",
                "description": "",
                "modelRef": "#/components/schemas/Flag",
                "customType": "Flag[]",
                "schema": [
                  {
                    "name": "account_id",
                    "kind": "optional",
                    "type": "integer<int64>",
                    "description": "The ID of the Account this Flag belongs to",
                    "format": "int64"
                  },
                  {
                    "name": "archive_url",
                    "kind": "optional",
                    "type": "object",
                    "readOnly": true,
                    "description": "",
                    "complexType": "allOf",
                    "complexItems": [
                      {
                        "name": "UrlValue",
                        "description": "",
                        "modelRef": "#/components/schemas/UrlValue",
                        "schema": []
                      }
                    ],
                    "schema": []
                  },
                  {
                    "name": "archived",
                    "kind": "optional",
                    "type": "boolean",
                    "description": "",
                    "example": false
                  },
                  {
                    "name": "created_by_user_email",
                    "kind": "optional",
                    "type": "string",
                    "readOnly": true,
                    "description": "",
                    "example": "testuser@optimizely.com"
                  },
                  {
                    "name": "created_time",
                    "kind": "required",
                    "type": "string<date-time>",
                    "readOnly": true,
                    "description": "",
                    "example": "2019-05-08T00:00:00.000Z",
                    "format": "date-time"
                  },
                  {
                    "name": "delete_url",
                    "kind": "optional",
                    "type": "object",
                    "readOnly": true,
                    "description": "",
                    "complexType": "allOf",
                    "complexItems": [
                      {
                        "name": "UrlValue",
                        "description": "",
                        "modelRef": "#/components/schemas/UrlValue",
                        "schema": []
                      }
                    ],
                    "schema": []
                  },
                  {
                    "name": "description",
                    "kind": "optional",
                    "type": "string",
                    "description": "",
                    "example": "Flag used for driving customers to use recurring deposits by showing a graph of compound interest over time"
                  },
                  {
                    "name": "environments",
                    "kind": "required",
                    "type": "map",
                    "readOnly": true,
                    "description": "",
                    "example": "",
                    "customType": "map<string, FlagEnvironment>",
                    "schema": []
                  },
                  {
                    "name": "id",
                    "kind": "required",
                    "type": "integer",
                    "readOnly": true,
                    "description": "",
                    "example": 45633994
                  },
                  {
                    "name": "is_permanent",
                    "kind": "optional",
                    "type": "boolean",
                    "description": "<p>When true, marks the flag as intentionally permanent (e.g. a kill switch or operational toggle) so governance tooling excludes it from stale scoring and archive recommendations.</p>",
                    "example": false,
                    "default": false
                  },
                  {
                    "name": "key",
                    "kind": "required",
                    "type": "string",
                    "description": "",
                    "example": "recurring_deposit"
                  },
                  {
                    "name": "name",
                    "kind": "required",
                    "type": "string",
                    "description": "",
                    "example": "Recurring Deposit"
                  },
                  {
                    "name": "outlier_filtering_enabled",
                    "kind": "optional",
                    "type": "boolean",
                    "description": "",
                    "example": false,
                    "default": false
                  },
                  {
                    "name": "owner_user_id",
                    "kind": "optional",
                    "type": "string",
                    "nullable": true,
                    "description": "<p>Unique user ID of the flag owner. This is the user's unique identifier, not their email address. If no value was provided during creation, this defaults to the user who created the flag.</p>",
                    "example": "1234-abcd-5678-efgh"
                  },
                  {
                    "name": "project_id",
                    "kind": "optional",
                    "type": "integer<int64>",
                    "description": "The ID of the Project this Flag belongs to",
                    "format": "int64"
                  },
                  {
                    "name": "revision",
                    "kind": "optional",
                    "type": "integer",
                    "readOnly": true,
                    "description": "Revision number for tracking changes"
                  },
                  {
                    "name": "role",
                    "kind": "optional",
                    "type": "string",
                    "readOnly": true,
                    "description": "Granular permission role",
                    "example": "admin"
                  },
                  {
                    "name": "team_ids",
                    "kind": "optional",
                    "type": "array",
                    "description": "List of team IDs associated with this flag",
                    "example": "[\"1234567890\",\"0987654321\"]",
                    "default": [],
                    "itemType": "string",
                    "customType": "string[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "unarchive_url",
                    "kind": "optional",
                    "type": "object",
                    "readOnly": true,
                    "description": "",
                    "complexType": "allOf",
                    "complexItems": [
                      {
                        "name": "UrlValue",
                        "description": "",
                        "modelRef": "#/components/schemas/UrlValue",
                        "schema": []
                      }
                    ],
                    "schema": []
                  },
                  {
                    "name": "update_url",
                    "kind": "optional",
                    "type": "object",
                    "readOnly": true,
                    "description": "",
                    "complexType": "allOf",
                    "complexItems": [
                      {
                        "name": "UrlValue",
                        "description": "",
                        "modelRef": "#/components/schemas/UrlValue",
                        "schema": []
                      }
                    ],
                    "schema": []
                  },
                  {
                    "name": "updated_time",
                    "kind": "required",
                    "type": "string<date-time>",
                    "readOnly": true,
                    "description": "",
                    "example": "2019-05-08T00:00:00.000Z",
                    "format": "date-time"
                  },
                  {
                    "name": "url",
                    "kind": "required",
                    "type": "object",
                    "readOnly": true,
                    "description": "Link to self",
                    "complexType": "allOf",
                    "complexItems": [
                      {
                        "name": "UrlValue",
                        "description": "",
                        "modelRef": "#/components/schemas/UrlValue",
                        "schema": []
                      }
                    ],
                    "schema": []
                  },
                  {
                    "name": "urn",
                    "kind": "required",
                    "type": "string",
                    "readOnly": true,
                    "description": "The URN for the Flag",
                    "example": "flags.flag.optimizely.com::asdfsdf-2344-efadf03-343434-efrrr"
                  },
                  {
                    "name": "variable_definitions",
                    "kind": "optional",
                    "type": "map",
                    "description": "",
                    "example": "",
                    "default": {},
                    "customType": "map<string, VariableDefinition>",
                    "schema": []
                  }
                ]
              },
              {
                "name": "last_url",
                "kind": "required",
                "type": "object",
                "description": "Link to the last page of Flags in a series.",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "UrlValue",
                    "description": "",
                    "modelRef": "#/components/schemas/UrlValue",
                    "schema": []
                  }
                ],
                "schema": []
              },
              {
                "name": "next_url",
                "kind": "optional",
                "type": "object",
                "description": "<p>List of links to next pages of Flags in a series.</p>\n<p>The first element in the array is the exact next page after the current record, etc.</p>",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "UrlList",
                    "description": "",
                    "modelRef": "#/components/schemas/UrlList",
                    "schema": []
                  }
                ],
                "schema": []
              },
              {
                "name": "page",
                "kind": "required",
                "type": "integer",
                "description": "<p>Number of the current page. 1-index based.</p>",
                "example": 5
              },
              {
                "name": "prev_url",
                "kind": "optional",
                "type": "object",
                "description": "<p>List of links to previous pages of Flags in a series.</p>\n<p>The first element in the array is the exact previous page before the current record, etc.</p>",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "UrlList",
                    "description": "",
                    "modelRef": "#/components/schemas/UrlList",
                    "schema": []
                  }
                ],
                "schema": []
              },
              {
                "name": "reset_url",
                "kind": "optional",
                "type": "object",
                "description": "Link to the default pages of Flags",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "UrlValue",
                    "description": "",
                    "modelRef": "#/components/schemas/UrlValue",
                    "schema": []
                  }
                ],
                "schema": []
              },
              {
                "name": "sort_url",
                "kind": "optional",
                "type": "object",
                "description": "<p>Url template like '.../{?sort}'</p>",
                "complexType": "allOf",
                "complexItems": [
                  {
                    "name": "UrlValue",
                    "description": "",
                    "modelRef": "#/components/schemas/UrlValue",
                    "schema": []
                  }
                ],
                "schema": []
              },
              {
                "name": "total_count",
                "kind": "required",
                "type": "integer",
                "description": "Total number of Flags 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/Flags",
            "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": "_LPZSaAb3qw4QNXV9o1WT",
          "language": "curl",
          "label": "cURL",
          "code": "curl --request GET \\\n     --url https://api.optimizely.com/flags/v1//projects/{project_id}/flags \\\n     --header 'accept: application/json'"
        },
        {
          "id": "__0u5NxXTrFsLgGyG1Gmn",
          "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}/flags\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));"
        },
        {
          "id": "JGZRErJhvp6CCkz2JkqRn",
          "language": "ruby",
          "label": "Ruby",
          "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.optimizely.com/flags/v1//projects/{project_id}/flags\")\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": "-sLT9BczOuiBmM416NT1K",
          "language": "python",
          "label": "Python",
          "code": "import requests\nimport json\n\nurl = \"https://api.optimizely.com/flags/v1//projects/{project_id}/flags\"\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": "_LPZSaAb3qw4QNXV9o1WT"
    },
    "results": {
      "languages": [
        {
          "id": "response-0-200",
          "language": "200",
          "code": "// Successful retrieval of a page of Flags.\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  \"create_url\": {},\n  \"fetch_flag_url\": {},\n  \"filter_url\": {},\n  \"first_url\": {},\n  \"items\": [\n    {\n      \"account_id\": \"\",\n      \"archive_url\": {},\n      \"archived\": false,\n      \"created_by_user_email\": \"testuser@optimizely.com\",\n      \"created_time\": \"2019-05-08T00:00:00.000Z\",\n      \"delete_url\": {},\n      \"description\": \"Flag used for driving customers to use recurring deposits by showing a graph of compound interest over time\",\n      \"environments\": \"\",\n      \"id\": 45633994,\n      \"is_permanent\": false,\n      \"key\": \"recurring_deposit\",\n      \"name\": \"Recurring Deposit\",\n      \"outlier_filtering_enabled\": false,\n      \"owner_user_id\": \"1234-abcd-5678-efgh\",\n      \"project_id\": \"\",\n      \"revision\": 0,\n      \"role\": \"admin\",\n      \"team_ids\": [\n        \"\"\n      ],\n      \"unarchive_url\": {},\n      \"update_url\": {},\n      \"updated_time\": \"2019-05-08T00:00:00.000Z\",\n      \"url\": {},\n      \"urn\": \"flags.flag.optimizely.com::asdfsdf-2344-efadf03-343434-efrrr\",\n      \"variable_definitions\": \"\"\n    }\n  ],\n  \"last_url\": {},\n  \"next_url\": {},\n  \"page\": 5,\n  \"prev_url\": {},\n  \"reset_url\": {},\n  \"sort_url\": {},\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": ""
    }
  ]
}