---
type: api
title: Get roles
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch-serverless/operation/operation-security-get-role
resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch-serverless/operation/operation-security-get-role
products:
  - Elasticsearch Serverless
---

# Get roles


## Paths

- `GET` `/_security/role/{name}`
- `GET` `/_security/role`

#### Path parameters

- `name` (union string | string[]) — optional, leave it out to use `/_security/role`
  The name of the role.
You can specify multiple roles as a comma-separated list.
If you do not specify this parameter, the API returns information about all roles.

## Description

Get roles in the native realm.
The role management APIs are generally the preferred way to manage roles, rather than using file-based role management.
The get roles API cannot retrieve roles that are defined in roles files.

## Required authorization

- Cluster privileges: `read_security`

## Authentication

- Api key: `Authorization: <value>`
  Elasticsearch APIs use key-based authentication.
  You must create an API key and use the encoded value in the request header.
  For example:
  
  
  ```
  curl -X GET "${ES_URL}/_cat/indices?v=true" \
    -H "Authorization: ApiKey ${API_KEY}"
  ```
  
  For more information about where to find API keys for the Elasticsearch endpoint (${ES_URL}) for a project, go to [Get started with Elasticsearch Serverless](https://www.elastic.co/docs/solutions/search/serverless-elasticsearch-get-started).

## Query string parameters

- `include_implicit` (boolean · default: false) — optional
  If `true`, include privileges that are implicitly granted by registered `ImplicitPrivilegesProviders` alongside the explicitly configured privileges.
Each implicit entry in the response is annotated with `implicitly_granted: true`.

## Response

`application/json`

- `<string>` (object)
  - `cluster` (union anyOf[])
    Values: `all`, `cancel_task`, `manage`, `manage_api_key`, `manage_behavioral_analytics`, `manage_enrich`, `manage_esql`, `manage_index_templates`, `manage_inference`, `manage_ingest_pipelines`, `manage_logstash_pipelines`, `manage_ml`, `manage_own_api_key`, `manage_pipeline`, `manage_reindex`, `manage_search_application`, `manage_search_query_rules`, `manage_search_synonyms`, `manage_security`, `manage_transform`, `monitor`, `monitor_enrich`, `monitor_esql`, `monitor_inference`, `monitor_ml`, `monitor_reindex`, `monitor_transform`, `none`, `post_behavioral_analytics_event`, `read_pipeline`, `read_security`, `read_project_routing`, `manage_project_routing`
  - `indices` (object[])
    - `implicitly_granted` (boolean)
      Set to `true` on entries that were contributed by a registered `ImplicitPrivilegesProvider`
rather than explicitly stored on the role. Only present when the get role API is called with
`include_implicit=true`. The put role API rejects this field, so clients must not echo it back
on a GET-then-PUT round-trip.
    - `field_security` (object)
      The document fields that the owners of the role have read access to.
      - `except` (string)
      - `grant` (string)
    - `names` (union string | string[])
      A list of indices (or index name patterns) to which the permissions in this entry apply.
    - `privileges` (union anyOf[])
      The index level privileges that owners of the role have on the specified indices.
      Values: `all`, `auto_configure`, `create`, `create_doc`, `create_index`, `create_view`, `delete`, `delete_index`, `delete_view`, `index`, `maintenance`, `manage`, `manage_data_stream_lifecycle`, `manage_view`, `monitor`, `none`, `read`, `read_view_metadata`, `view_index_metadata`, `write`
    - `query` (union)
      A search query that defines the documents the owners of the role have access to. A document within the specified indices must match this query for it to be accessible by the owners of the role.
  - `metadata` (object)
  - `description` (string)
  - `run_as` (string[])
  - `transient_metadata` (map string to object)
  - `applications` (object[])
    - `application` (string)
      The name of the application to which this entry applies.
    - `privileges` (string[])
      A list of strings, where each element is the name of an application privilege or action.
    - `resources` (string[])
      A list resources to which the privileges are applied.
  - `role_templates` (object[])
    - `format` (enum)
      Values: `string`, `json`
    - `template` (string)
  - `global` (map string to string to string to string)
## Code examples

#### Console

```console
GET /_security/role/my_admin_role
```

#### JavaScript

```javascript
const response = await client.security.getRole({
  name: "my_admin_role",
});
```

#### Python

```python
resp = client.security.get_role(
    name="my_admin_role",
)
```

#### curl

```curl
curl -X GET "$ELASTICSEARCH_URL/_security/role/my_admin_role" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY"
```

#### Java

```java
client.security().getRole(g -> g
    .name("my_admin_role")
);
```

#### C#

```c#
var response = await client.Security
    .GetRoleAsync(d1 => d1
        .Name(new[] { "my_admin_role" })
    );
```

#### PHP

```php
$resp = $client->security()->getRole([
    "name" => "my_admin_role",
]);
```

#### Ruby

```ruby
response = client.security.get_role(
  name: "my_admin_role"
)
```

## Response examples

#### Security get role response example1

A successful response from `GET /_security/role/my_admin_role`. The response contains information about the `my_admin_role` role in the native realm.

```json
{
  "my_admin_role": {
    "description": "Grants full access to all management features within the cluster.",
    "cluster" : [ "all" ],
    "indices" : [
      {
        "names" : [ "index1", "index2" ],
        "privileges" : [ "all" ],
        "allow_restricted_indices" : false,
        "field_security" : {
          "grant" : [ "title", "body" ]}
      }
    ],
    "applications" : [ ],
    "run_as" : [ "other_user" ],
    "metadata" : {
      "version" : 1
    },
    "transient_metadata": {
      "enabled": true
    }
  }
}
```