[role="xpack"]
[testenv="platinum"]
[[ml-get-filter]]
= Get filters API
++++
<titleabbrev>Get filters</titleabbrev>
++++

Retrieves filters.

[[ml-get-filter-request]]
== {api-request-title}

`GET _ml/filters/<filter_id>` +

`GET _ml/filters/`

[[ml-get-filter-prereqs]]
== {api-prereq-title}

Requires the `manage_ml` cluster privilege. This privilege is included in the 
`machine_learning_admin` built-in role.

[[ml-get-filter-desc]]
== {api-description-title}

You can get a single filter or all filters. For more information, see 
{ml-docs}/ml-rules.html[Machine learning custom rules].

[[ml-get-filter-path-parms]]
== {api-path-parms-title}

`<filter_id>`::
(Optional, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=filter-id]

[[ml-get-filter-query-parms]]
== {api-query-parms-title}

`from`::
    (Optional, integer) Skips the specified number of filters. Defaults to `0`.

`size`::
    (Optional, integer) Specifies the maximum number of filters to obtain.
    Defaults to `100`.

[[ml-get-filter-results]]
== {api-response-body-title}

The API returns an array of filter resources, which have the following
properties:

`description`::
(string) A description of the filter.

`filter_id`::
(string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=filter-id]
  
`items`::
(array of strings) An array of strings which is the filter item list.

[[ml-get-filter-example]]
== {api-examples-title}

[source,console]
--------------------------------------------------
GET _ml/filters/safe_domains
--------------------------------------------------
// TEST[skip:setup:ml_filter_safe_domains]

The API returns the following results:

[source,console-result]
----
{
  "count": 1,
  "filters": [
    {
      "filter_id": "safe_domains",
      "description": "A list of safe domains",
      "items": [
        "*.google.com",
        "wikipedia.org"
      ]
    }
  ]
}
----
