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 or Invite team member 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 for what each built-in role can access.

Roles are organization-scoped, so no team_name is required — 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.

GET https://betterstack.com/api/v2/roles

Headers

Authorization

required string

Bearer $TOKEN

200

Returns the organization's roles.

Response 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"
      }
    }
  ]
}

401

Authentication failed due to a missing or invalid token.

Response body

{
  "errors": "We could not authenticate your request. Please provide a valid Global API token or Uptime API token."
}

Explore documentation

Example cURL

Explore documentation

List roles

Example cURL

Please accept cookies