# List roles

Lists all roles in your organization — the five built-in roles (`admin`, `billing_admin`, `team_lead`, `responder`, `member`) and any custom roles. Use a role's `id` with the [Update team member role](https://betterstack.com/docs/uptime/api/team-members/change-role/) or [Invite team member](https://betterstack.com/docs/uptime/api/team-members/invite/) APIs.

The `role` attribute is the system-role identifier, or `custom` for a custom role. Custom roles share the value `custom`, so identify them by their `id` and `name`. See [Manage roles
](https://betterstack.com/docs/uptime/team-management/manage-roles/) for what each built-in role can access.

Roles are organization-scoped, so no `team_name` is required — a [global API token](https://betterstack.com/docs/uptime/api/getting-started-with-uptime-api/#get-a-global-api-token) spanning multiple teams lists the organization's roles directly. The built-in roles are returned first (in the order above), then custom roles. The endpoint is not paginated, so a single response always contains every role.

[endpoint]
base_url = "https://betterstack.com"
path = "/api/v2/roles"
method = "GET"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 200
description = '''Returns the organization's roles.'''
body = '''{
  "data": [
    { "id": "101", "type": "role", "attributes": { "name": "Admin", "role": "admin" } },
    { "id": "102", "type": "role", "attributes": { "name": "Billing admin", "role": "billing_admin" } },
    { "id": "103", "type": "role", "attributes": { "name": "Team lead", "role": "team_lead" } },
    { "id": "104", "type": "role", "attributes": { "name": "Responder", "role": "responder" } },
    { "id": "105", "type": "role", "attributes": { "name": "Member", "role": "member" } },
    { "id": "206", "type": "role", "attributes": { "name": "On-call lead", "role": "custom" } }
    ]
  }'''

[[response]]
status = 401
description = '''Authentication failed due to a missing or invalid token.'''
body = '''{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Uptime API token."
}'''
[/responses]

#### Example cURL

```shell
[label List roles]
curl --request GET \
  --url "https://betterstack.com/api/v2/roles" \
  --header "Authorization: Bearer $TOKEN"
```