> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.
# list_roles
> List your company's permission roles alphabetically with a name/id filter and pagination; each row carries the role's headcount, default and admin flags.
List your company's permission roles and how many users hold each.
A role is what decides what a user may see and do; use `get_role` for the
permissions behind one. Reach for this to answer questions about the shape of
the organisation's access — how many people are admins, which roles exist, which
one new users get by default. Rows are ordered alphabetically by role name
(A→Z).
Qobra support's own god role is never listed, and the headcount counts
non-archived users only.
This tool needs the company-settings *roles* permission (READ on the Role
company setting). The web app does not require it for a caller merely reading
role names, but an organisation's permission structure is administrative data,
and gating it like `get_role` means a caller who can list a role can always
read it.
## Parameters
Filter matched against the role name (case-insensitive substring) or, when
it is a valid ObjectId, against the role id.
Page size, between 1 and 250. Defaults to 50.
Row offset into the result set — the number of rows to skip before this
page. Any offset >= 0 is accepted; it does not have to be a multiple of
limit, so you can start from an arbitrary row. Pass the next\_offset returned
by the previous call to walk the pages, or None for the first page.
## Response
Deep link to open this role in the Qobra web app.
Whether this is the role newly-created users get unless another one is
picked. Exactly one role of a company is the default.
Whether this is the company's built-in Admin role, which holds every
permission and cannot be edited.
Number of non-archived users currently holding this role.