---
title: "List roles"
method: GET
path: "/role"
tags: ["Roles"]
---

# List roles

`GET /role`

## Request

- Base URL: `https://api.elaichi.ai`
- URL: `https://api.elaichi.ai/role`
- Auth: HTTP bearer

Roles in this organization, system and custom alike. Any member may read them — this is what populates a role picker before `PATCH /member/{userId}` or `POST /invite`.

## Query parameters

- `limit` integer
- `cursor` string

## Headers

- `X-Organization-Id` string

## Response `200`

OK

- object
  - `result` Role[], required
    - `id` string: Role id (`role_…`).
    - `name` string
    - `description` string, nullable
    - `is_system` boolean: Predefined roles ship with every organization and cannot be edited away.
    - `seat_class` 'billable' | 'free_admin': Whether members holding only this role count toward billable seats.
    - `permissions` string[]: Every permission the role holds, including any `GET /permission` does not list for this organization (for example the Apps permissions while Apps are unavailable). `PATCH /role/{id}` replaces this list wholesale, so send back the entries you did not mean to remove.
    - `permission_count` integer: How many of `permissions` `GET /permission` lists for this organization: the number to show beside the role. Can be lower than `permissions.length`.
    - `member_count` integer: How many members hold this role right now. `GET /member?role_id={id}` lists them; while it is above zero, `DELETE /role/{id}` needs `reassign_to` (or, on `POST /role/{id}/delete`, `reassign_to` and/or a `reassignments` entry for every holder).
    - `pending_invite_count` integer: Pending invites issued for this role. Present only on roles you can manage. While above zero, `DELETE /role/{id}` and `POST /role/{id}/delete` need `reassign_to`, which re-points them.
    - `group_mapping_count` integer: SCIM group mappings that assign this role. Present only on roles you can manage. While above zero, `DELETE /role/{id}` is refused (`409 role_mapped`) until the mappings change.
    - `can_reassign_holders` boolean: Whether you may move this role's holders and pending invites to another role (`DELETE /role/{id}?reassign_to=` or `POST /role/{id}/delete`): you hold `member:manage` and do not hold this role yourself.
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `next_cursor` string, nullable, required
  - `prev_cursor` string, nullable, required

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `429`: Rate limited

---

[API](https://skmtc.dev/elaichi/apis/elaichi-api.md) · [All operations](https://skmtc.dev/elaichi/apis/elaichi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/elaichi/apis/elaichi-api/revisions/b22cfb7b6d15?raw)