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

# List roles

`GET /api/v3/roles/`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/roles/`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/docs/api/v3/roles/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns every role visible to the agency: non-internal system roles
(Workspace Admin, Editor, Viewer, etc.) plus all agency-scoped custom roles.
Each entry carries `user_count` — the number of users currently assigned to that role.

## Response `200`

List of roles

- RoleListResponse
  - `roles` Role[], required
    - `id` integer, required: Role ID
    - `title` string, required: Role title (unique within the agency)
    - `description` string, required: Optional human-readable description
    - `is_system` boolean, required: True for built-in Improvado-managed roles. Read-only — cannot be edited or deleted.
    - `is_internal` boolean, required: True for internal-only roles (impersonation, guest viewers). These are never listed in the API.
    - `layers` object, required: Permissions grouped by product layer. Layer codes match `code` in the permissions catalog.
    - `user_count` integer, required: Number of users currently assigned to this role across the agency.

## Other responses

- `401`: Authentication credentials were not provided.
- `403`: Agency does not have embedded API enabled, or caller is not an agency chief.

---

[API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)