---
title: "Get role"
method: GET
path: "/role/{id}"
tags: ["Roles"]
---

# Get role

`GET /role/{id}`

## Request

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

Returns one role with its permissions and member counts. Any member may read it.

## Path parameters

- `id` string, required

## Headers

- `X-Organization-Id` string

## Response `200`

OK

- Role
  - `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

## 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)