elasticsearch/docs/reference/cat/alias.asciidoc

[[cat-alias]]
=== cat aliases API
++++
<titleabbrev>cat aliases</titleabbrev>
++++

[IMPORTANT]
====
cat APIs are only intended for human consumption using the command line or the 
{kib} console. They are _not_ intended for use by applications. For application 
consumption, use the <<aliases,aliases API>>.
====

Retrieves the cluster's <<aliases,index aliases>>, including filter and routing
information. The API does not return data stream aliases.

[[cat-alias-api-request]]
==== {api-request-title}

`GET _cat/aliases/<alias>`

`GET _cat/aliases`

[[cat-alias-api-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have the
`view_index_metadata` or `manage` <<privileges-list-indices,index privilege>>
for any alias you retrieve.

[[cat-alias-api-path-params]]
==== {api-path-parms-title}

`<alias>`::
(Optional, string) Comma-separated list of aliases to retrieve. Supports
wildcards (`*`). To retrieve all aliases, omit this parameter or use `*` or
`_all`.

[[cat-alias-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=http-format]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-h]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=help]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=local]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-s]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-v]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]

[[cat-alias-api-example]]
==== {api-examples-title}

////
Hidden setup for example:
[source,console,id=cat-aliases-example]
----
PUT test1
{
  "aliases": {
    "alias1": {},
    "alias2": {
      "filter": {
        "match": {
          "user.id": "kimchy"
        }
      }
    },
    "alias3": {
      "routing": "1"
    },
    "alias4": {
      "index_routing": "2",
      "search_routing": "1,2"
    }
  }
}
----
////

[source,console]
----
GET _cat/aliases?v=true
----
// TEST[continued]

The API returns the following response:

[source,txt]
----
alias  index filter routing.index routing.search is_write_index
alias1 test1 -      -            -              -
alias2 test1 *      -            -              -
alias3 test1 -      1            1              -
alias4 test1 -      2            1,2            -
----
// TESTRESPONSE[s/[*]/[*]/ non_json]

This response shows that `alias2` has configured a filter, and specific routing
configurations in `alias3` and `alias4`.

If you only want to get information about specific aliases, you can specify 
the aliases in comma-delimited format as a URL parameter, e.g., 
/_cat/aliases/alias1,alias2.