--- title: List Approvals slug: feature-experimentation/api/list-approvals docTags: createdAt: 2026-10-13T18:16:15.508Z --- { "id": "pOkgirhsVvs60Vhsm74P5", "type": "api-oas-v2", "data": { "method": "GET", "url": "http://localhost:3002//projects/{project_id}/flags/approvals", "servers": [ { "url": "http://localhost:3002//projects/{project_id}/flags/approvals", "description": "Local server" }, { "url": "https://api.app.optimizely.com/flags-scheduling/projects/{project_id}/flags/approvals", "description": "Production server" } ], "name": "List Approvals", "description": "List Approvals of a Flag\n", "contentType": "application/json", "request": { "pathParameters": [ { "kind": "required", "name": "project_id", "type": "integer", "description": "The id of the project for which the Approval is scoped to." } ], "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", "type": "integer", "description": "

Bypass page_token to jump to specific page

", "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": "sort", "type": "array", "description": "Sort the Approvals based on the attributes\n", "schema": [], "itemType": "string", "customType": "string[]" }, { "kind": "optional", "name": "archived", "type": "boolean", "description": "

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

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

Filter the Approvals by status. An Approval may have a status of accepted (approval_status=accepted), withrdawn (approval_status=withdrawn), rejected (approval_status=rejected), or pending (approval_status=pending).

" }, { "kind": "optional", "name": "environment", "type": "array", "description": "Filter the Approval by the environment\n", "schema": [], "itemType": "string", "customType": "string[]" }, { "kind": "optional", "name": "query", "type": "string", "description": "Filter the Approvals by entity name or key substring\n" } ], "bodyDataParameters": [], "formDataParameters": [], "oAuthParameters": [ { "id": "BearerAuth", "name": "BearerAuth", "kind": "optional", "type": "http", "description": "

To get a personal token, see https://docs.developers.optimizely.com/web/docs/personal-token

", "scheme": "bearer" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "

Successful retrieval of a page of Approvals.\nThe response includes RESTful JSON (https://restfuljson.org/) styled links and pagination metadata. Objects in this API MAY include a url property for a link to itself and MAY append _url to properties for related links. If 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": "Approvals", "schema": [ { "name": "items", "kind": "required", "type": "array", "description": "List of Approvals.", "modelRef": "#/components/schemas/Approval", "customType": "Approval[]", "schema": [ { "name": "archived", "kind": "required", "type": "boolean", "description": "", "example": false }, { "name": "entity_name", "kind": "required", "type": "string", "description": "

The name of the entity this Approval relates to (e.g. Flag Name).

", "example": "Flag 123" }, { "name": "entity_key", "kind": "required", "type": "string", "description": "

The key of the entity this Approval relates to (e.g. Flag Key).

", "example": "flag_123" }, { "name": "entity_id", "kind": "required", "type": "integer", "description": "

The ID of the entity this Approval relates to (e.g. Flag ID).

", "example": 12345 }, { "name": "id", "kind": "required", "type": "integer", "description": "The approval ID.", "example": 1 }, { "name": "environment", "kind": "required", "type": "string", "description": "The environment where the action is happening.", "example": "development" }, { "name": "environment_id", "kind": "required", "type": "integer", "description": "The ID of environment where the action is happening.", "example": 2345 }, { "name": "current_status_id", "kind": "required", "type": "integer", "description": "The current status ID.", "example": 3333 }, { "name": "schedule", "kind": "optional", "type": "object", "description": "Schedule details.", "complexType": "allOf", "complexItems": [ { "name": "ScheduleTimeResponse", "description": "", "modelRef": "#/components/schemas/ScheduleTimeResponse", "schema": [ { "name": "date", "kind": "optional", "type": "string", "description": "

The schedule will run at this date. Expected format: yyyy-mm-dd.

", "example": "2025-02-18", "format": "date" }, { "name": "time", "kind": "optional", "type": "string", "description": "

The schedule will run at this time. Expected format: hh

(24 hour).

", "example": "23:59", "pattern": "^([01]?[0-9]|2[0-3]):([0-5][0-9])$" }, { "name": "time_zone", "kind": "optional", "type": "string", "description": "The timezone information for the scheduled time.", "example": "UTC" }, { "name": "utc_time", "kind": "optional", "type": "string", "description": "The utc timestamp when the scheduled job will be executed.", "example": "2025-02-18T23:59:59+00:00", "format": "date-time" } ] } ], "schema": [] }, { "name": "actions", "kind": "required", "type": "array", "description": "List of actions to be performed.", "modelRef": "#/components/schemas/FlagScheduleAction", "customType": "FlagScheduleAction[]", "schema": [ { "name": "subject", "kind": "required", "type": "object", "description": "The subject details for flag action", "example": "", "schema": [ { "name": "key", "kind": "optional", "type": "string", "description": "The key of the subject" }, { "name": "type", "kind": "optional", "type": "string", "description": "The type of the subject" } ] }, { "name": "changed_element", "kind": "optional", "type": "string", "description": "The element to be changed." }, { "name": "value", "kind": "required", "type": "object", "description": "

The value for changed_element.

", "example": "", "schema": [] } ] }, { "name": "status_history", "kind": "required", "type": "array", "description": "History of status changes.", "modelRef": "#/components/schemas/StatusHistoryItem", "customType": "StatusHistoryItem[]", "schema": [ { "name": "id", "kind": "required", "type": "integer", "description": "The ID of the status history item" }, { "name": "status", "kind": "required", "type": "string", "description": "The status value" }, { "name": "user_id", "kind": "required", "type": "integer", "description": "The ID of the user" }, { "name": "email", "kind": "required", "type": "string", "description": "The email of the user" }, { "name": "reason", "kind": "required", "type": "string", "description": "The reason for the status change" } ] }, { "name": "created_at", "kind": "required", "type": "string", "description": "Timestamp when the schedule was created.", "example": "2024-02-06T12:00:00Z", "format": "date-time" }, { "name": "updated_at", "kind": "required", "type": "string", "description": "Timestamp when the schedule was last updated.", "example": "2024-02-06T12:00:00Z", "format": "date-time" }, { "name": "created_by", "kind": "required", "type": "string", "description": "The user who created the schedule.", "example": "admin@example.com" }, { "name": "schedule_job_status", "kind": "required", "type": "string", "description": "The status of the scheduled job.", "example": "pending", "enum": [ "pending", "in_queue", "failed_to_queue", "canceled", "completed", "failed", "partially_failed" ] }, { "name": "policy_id", "kind": "optional", "type": "integer", "description": "The ID of the approval policy that governs this approval.", "example": 42 }, { "name": "policy_name", "kind": "optional", "type": "string", "description": "The name of the approval policy that governs this approval.", "example": "Production Gate" }, { "name": "is_current_user_approver", "kind": "optional", "type": "boolean", "nullable": true, "description": "

Whether the current user is an approver for this approval. true if the user can approve, false if not, null when the status is not pending or the approver cannot be resolved.

" } ] }, { "name": "total_count", "kind": "required", "type": "integer", "description": "Total number of approvals.", "example": 20 }, { "name": "count", "kind": "required", "type": "integer", "description": "Number of Approvals on the current page.", "example": 2 }, { "name": "has_more", "kind": "optional", "type": "boolean", "description": "Boolean indicating if there are more approvals available.", "example": true }, { "name": "page", "kind": "required", "type": "integer", "description": "

Current page number (1-based index).

", "example": 1 }, { "name": "total_pages", "kind": "required", "type": "integer", "description": "Total number of pages.", "example": 10 }, { "name": "first_url", "kind": "required", "type": "object", "description": "Link to the first page of approvals.", "complexType": "allOf", "complexItems": [ { "name": "UrlValue", "description": "", "modelRef": "#/components/schemas/UrlValue", "schema": [] } ], "schema": [] }, { "name": "last_url", "kind": "required", "type": "object", "description": "Link to the last page of approvals.", "complexType": "allOf", "complexItems": [ { "name": "UrlValue", "description": "", "modelRef": "#/components/schemas/UrlValue", "schema": [] } ], "schema": [] }, { "name": "next_url", "kind": "optional", "type": "object", "description": "List of links to the next pages of approvals in a series.", "complexType": "allOf", "complexItems": [ { "name": "UrlList", "description": "", "modelRef": "#/components/schemas/UrlList", "schema": [] } ], "schema": [] }, { "name": "prev_url", "kind": "optional", "type": "object", "description": "List of links to previous pages of approvals in a series.", "complexType": "allOf", "complexItems": [ { "name": "UrlList", "description": "", "modelRef": "#/components/schemas/UrlList", "schema": [] } ], "schema": [] } ], "modelRef": "#/components/schemas/Approvals", "isExpanded": true } ] }, { "statusCode": "401", "description": "Not Authenticated", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "example": "{\"details\":\"Not authenticated\",\"status\":401}", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "details", "kind": "required", "type": "string", "description": "Details of Error." }, { "name": "status", "kind": "required", "type": "integer", "description": "Status code of the response.", "example": 400 } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] }, { "statusCode": "422", "description": "Validation Error", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "HTTPValidationError", "schema": [ { "name": "detail", "kind": "optional", "type": "array", "description": "", "modelRef": "#/components/schemas/ValidationError", "customType": "ValidationError[]", "schema": [ { "name": "loc", "kind": "required", "type": "array", "description": "Path to the invalid value", "example": "", "itemType": "object", "customType": "object[]", "itemExample": "", "itemDefault": "" }, { "name": "msg", "kind": "required", "type": "string", "description": "Error message" }, { "name": "type", "kind": "required", "type": "string", "description": "Error type" } ] }, { "name": "status", "kind": "optional", "type": "integer", "description": "Status code of the response.", "example": 422 } ], "modelRef": "#/components/schemas/HTTPValidationError", "isExpanded": true } ] } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "c-S5HaivR2zwzhr4DqeOc", "language": "curl", "label": "cURL", "code": "curl --request GET \\\n --url http://localhost:3002//projects/{project_id}/flags/approvals \\\n --header 'accept: application/json'" }, { "id": "sXnQWPTuHXVXnDigRFMYq", "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(\"http://localhost:3002//projects/{project_id}/flags/approvals\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "t5i0v8s-jeMKHu87x5CVF", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"http://localhost:3002//projects/{project_id}/flags/approvals\")\n\nhttp = Net::HTTP.new(url.host, url.port);\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = http.request(request)\nputs response.read_body\n" }, { "id": "cT35W9hZSbLLY-Oa6gVS7", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"http://localhost:3002//projects/{project_id}/flags/approvals\"\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": "c-S5HaivR2zwzhr4DqeOc" }, "results": { "languages": [ { "id": "CRmfObin8mquOtQGnYkb3", "language": "200", "code": "// Successful retrieval of a page of Approvals.\nThe response includes RESTful JSON (https://restfuljson.org/) styled links and pagination metadata. Objects in this API MAY include a url property for a link to itself and MAY append _url to properties for related links. If a link is not present in the response, it indicates a user is not authorized to access the related resource.\n{\n \"items\": [\n {\n \"archived\": false,\n \"entity_name\": \"Flag 123\",\n \"entity_key\": \"flag_123\",\n \"entity_id\": 12345,\n \"id\": 1,\n \"environment\": \"development\",\n \"environment_id\": 2345,\n \"current_status_id\": 3333,\n \"schedule\": {},\n \"actions\": [\n {\n \"subject\": {\n \"key\": \"\",\n \"type\": \"\"\n },\n \"changed_element\": \"\",\n \"value\": {}\n }\n ],\n \"status_history\": [\n {\n \"id\": 0,\n \"status\": \"\",\n \"user_id\": 0,\n \"email\": \"\",\n \"reason\": \"\"\n }\n ],\n \"created_at\": \"2024-02-06T12:00:00Z\",\n \"updated_at\": \"2024-02-06T12:00:00Z\",\n \"created_by\": \"admin@example.com\",\n \"schedule_job_status\": \"pending\",\n \"policy_id\": 42,\n \"policy_name\": \"Production Gate\",\n \"is_current_user_approver\": false\n }\n ],\n \"total_count\": 20,\n \"count\": 2,\n \"has_more\": true,\n \"page\": 1,\n \"total_pages\": 10,\n \"first_url\": {},\n \"last_url\": {},\n \"next_url\": {},\n \"prev_url\": {}\n}" }, { "id": "C6Yj6KE7e5KwlZBuWABWq", "language": "401", "code": "// Not Authenticated\n{\n \"details\": \"\",\n \"status\": 400\n}" }, { "id": "N9k3-4ZBkrhmf3DYBl4dk", "language": "422", "code": "// Validation Error\n{\n \"detail\": [\n {\n \"loc\": [\n {}\n ],\n \"msg\": \"\",\n \"type\": \"\"\n }\n ],\n \"status\": 422\n}" } ], "selectedLanguageId": "CRmfObin8mquOtQGnYkb3" } }, "children": [ { "text": "" } ] }