# Find roles with a query


**POST /_security/_query/role**

**All methods and paths for this operation:**

<div>
                      <span class="operation-verb get">GET</span>
                      <span class="operation-path">/_security/_query/role</span>
                      </div>
                    <div>
                      <span class="operation-verb post">POST</span>
                      <span class="operation-path">/_security/_query/role</span>
                      </div>
                    

Get roles in a paginated manner.
The role management APIs are generally the preferred way to manage roles, rather than using file-based role management.
The query roles API does not retrieve roles that are defined in roles files, nor built-in ones.
You can optionally filter the results with a query.
Also, the results can be paginated and sorted.

## Required authorization

* Cluster privileges: `read_security`



## Servers
- http://api.example.com: http://api.example.com ()


## Authentication methods
- Api key auth
- Basic auth
- Bearer auth


## Parameters



### Body: application/json (object)

- **query** (object)
  A query to filter which roles to return.
  If the query parameter is missing, it is equivalent to a `match_all` query.
  The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`,
  `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`.
  You can query the following information associated with roles: `name`, `description`, `metadata`,
  `applications.application`, `applications.privileges`, and `applications.resources`.
- **from** (number)
  The starting document offset.
  It must not be negative.
  By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.
  To page through more hits, use the `search_after` parameter.
- **sort** (string | object | array[string | object])
  The sort definition.
  You can sort on `name`, `description`, `metadata`, `applications.application`, `applications.privileges`,
  and `applications.resources`.
  In addition, sort can also be applied to the `_doc` field to sort by index order.
- **size** (number)
  The number of hits to return.
  It must not be negative.
  By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters.
  To page through more hits, use the `search_after` parameter.
- **search_after** (array[number | string | boolean | null])
  The search after definition.


## Responses
### 200


#### Body: application/json (object)
- **total** (number)
  The total number of roles found.
- **count** (number)
  The number of roles returned in the response.
- **roles** (array[object])
  A list of roles that match the query.
  The returned role format is an extension of the role definition format.
  It adds the `transient_metadata.enabled` and the `_sort` fields.
  `transient_metadata.enabled` is set to `false` in case the role is automatically disabled, for example when the role grants privileges that are not allowed by the installed license.
  `_sort` is present when the search query sorts on some field.
  It contains the array of values that have been used for sorting.


[Powered by Bump.sh](https://bump.sh)