Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation
Theme

Suggested
Overview Models Agents Tools Audio & voice Production API reference

List organization roles

admin.organization.roles.list(**kwargs) -> SyncNextCursorPage[Role]
GET
/organization/roles

Lists the roles configured for the organization.

Parameters
after: Optional[str]

Cursor for pagination. Provide the value from the previous response’s next field to continue listing roles.

limit: Optional[int]

A limit on the number of roles to return. Defaults to 1000.

minimum0
maximum1000
order: Optional[Literal["asc", "desc"]]

Sort order for the returned roles.

Returns
class Role: …

Details about a role that can be assigned through the public Roles API.

id: str

Identifier for the role.

description: Optional[str]

Optional description of the role.

name: str

Unique name for the role.

object: Literal["role"]

Always role.

permissions: List[str]

Permissions granted by the role.

predefined_role: bool

Whether the role is predefined and managed by OpenAI.

resource_type: str

Resource type the role is bound to (for example api.organization or api.project).

List organization roles

import os
from openai import OpenAI

client = OpenAI(
    admin_api_key=os.environ.get("OPENAI_ADMIN_KEY"),  # This is the default and can be omitted
)
page = client.admin.organization.roles.list()
page = page.data[0]
print(page.id)
Response example
{
    "object": "list",
    "data": [
        {
            "object": "role",
            "id": "role_01J1F8ROLE01",
            "name": "API Group Manager",
            "description": "Allows managing organization groups",
            "permissions": [
                "api.groups.read",
                "api.groups.write"
            ],
            "resource_type": "api.organization",
            "predefined_role": false
        }
    ],
    "has_more": false,
    "next": null
}
Returns Examples
Response example
{
    "object": "list",
    "data": [
        {
            "object": "role",
            "id": "role_01J1F8ROLE01",
            "name": "API Group Manager",
            "description": "Allows managing organization groups",
            "permissions": [
                "api.groups.read",
                "api.groups.write"
            ],
            "resource_type": "api.organization",
            "predefined_role": false
        }
    ],
    "has_more": false,
    "next": null
}