---
type: api
title: Query roles
description: Query Kibana roles with optional filters, paging, and sorting.
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana/v9/operation/operation-post-security-role-query
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/kibana/v9/operation/operation-post-security-role-query
products:
  - Kibana
---

# Query roles

- Server: `https://{kibana_url}`

## Paths

- `POST` `/api/security/role/_query`

## Description

Query Kibana roles with optional filters, paging, and sorting.

## Authentication

- Api key: `Authorization: <value>`
  These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`
- Basic: `Authorization: Basic <credentials>`

## Header parameters

- `kbn-xsrf` (string) — required
  A required header to protect against CSRF attacks

## Request body

`application/json`

- `filters` (object) — optional
  The filter criteria for the query.
  - `showReservedRoles` (boolean) — optional
- `from` (number) — optional
- `query` (string) — optional
- `size` (number) — optional
- `sort` (object) — optional
  The sort criteria for the query.
  - `direction` (enum) — required
    Values: `asc`, `desc`
  - `field` (string) — required

## Response

Indicates a successful call.

`application/json`

- `count` (number)
  The number of roles returned in this response page.
- `roles` (object[])
  - `_transform_error` (object[])
    - `reason` (string)
      The reason the role could not be fully transformed.
    - `state` (object[])
      - `application` (string)
      - `privileges` (string[])
      - `resources` (string[])
  - `_unrecognized_applications` (string[])
  - `description` (string)
    A description for the role.
  - `elasticsearch` (object)
    The Elasticsearch cluster, index, and remote cluster security privileges for the role.
    - `cluster` (string[] · max items: 100)
    - `indices` (object[] · max items: 1000)
      - `allow_restricted_indices` (boolean)
        Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field covers the restricted indices too.
      - `field_security` (map string to string)
        Map values (string[] · max items: 1000)
      - `names` (string[] · min items: 1 · max items: 100)
      - `privileges` (string[] · min items: 1 · max items: 100)
      - `query` (string)
        A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.
    - `remote_cluster` (object[] · max items: 100)
      - `clusters` (string[] · min items: 1 · max items: 100)
      - `privileges` (string[] · min items: 1 · max items: 100)
    - `remote_indices` (object[] · max items: 1000)
      - `allow_restricted_indices` (boolean)
        Restricted indices are a special category of indices that are used internally to store configuration data and should not be directly accessed. Only internal system roles should normally grant privileges over the restricted indices. Toggling this flag is very strongly discouraged because it could effectively grant unrestricted operations on critical data, making the entire system unstable or leaking sensitive information. If for administrative purposes you need to create a role with privileges covering restricted indices, however, you can set this property to true. In that case, the names field will cover the restricted indices too.
      - `clusters` (string[] · min items: 1 · max items: 100)
      - `field_security` (map string to string)
        Map values (string[] · max items: 1000)
      - `names` (string[] · min items: 1 · max items: 100)
      - `privileges` (string[] · min items: 1 · max items: 100)
      - `query` (string)
        A search query that defines the documents the role members have read access to. A document within the specified data streams and indices must match this query in order for it to be accessible by the role members.
    - `run_as` (string[] · max items: 100)
  - `kibana` (object[])
    - `_reserved` (string[])
    - `base` (string[])
    - `feature` (map string to string)
    - `spaces` (string[])
  - `metadata` (map string to object)
  - `name` (string)
    The role name.
  - `transient_metadata` (map string to object)
- `total` (number)
  The total number of roles that match the query.
## Code examples

#### Console

```console
POST kbn:/api/security/role/_query
{
  "from": 0,
  "query": "kibana",
  "size": 25,
  "sort": {
    "direction": "asc",
    "field": "name"
  }
}
```

#### curl

```curl
curl -X POST "${KIBANA_URL}/api/security/role/_query" \
  -H "kbn-xsrf: true" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "from": 0,
    "query": "kibana",
    "size": 25,
    "sort": {
      "direction": "asc",
      "field": "name"
    }
  }'
```

## Response examples

#### Query roles

```json
{
  "count": 1,
  "roles": [
    {
      "_unrecognized_applications": [],
      "description": "My custom Kibana role.",
      "elasticsearch": {
        "cluster": [
          "monitor"
        ],
        "indices": [
          {
            "names": [
              "logs-*"
            ],
            "privileges": [
              "read"
            ]
          }
        ],
        "run_as": []
      },
      "kibana": [
        {
          "base": [
            "read"
          ],
          "feature": {},
          "spaces": [
            "default"
          ]
        }
      ],
      "metadata": {},
      "name": "my_kibana_role",
      "transient_metadata": {
        "enabled": true
      }
    }
  ],
  "total": 1
}
```