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

Retrieves {anomaly-job} results for one or more categories.

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

`GET _ml/anomaly_detectors/<job_id>/results/categories` +

`GET _ml/anomaly_detectors/<job_id>/results/categories/<category_id>`

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

* If the {es} {security-features} are enabled, you must have `monitor_ml`,
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. You also
need `read` index privilege on the index that stores the results. The
`machine_learning_admin` and `machine_learning_user` roles provide these
privileges. See <<security-privileges>> and
<<built-in-roles>>.

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

When `categorization_field_name` is specified in the job configuration, it is
possible to view the definitions of the resulting categories. A category
definition describes the common terms matched and contains examples of matched
values.

The anomaly results from a categorization analysis are available as bucket,
influencer, and record results. For example, the results might indicate that
at 16:45 there was an unusual count of log message category 11. You can then
examine the description and examples of that category. For more information, see
{ml-docs}/ml-configuring-categories.html[Categorizing log messages].

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

`<category_id>`::
(Optional, long) Identifier for the category. If you do not specify this
parameter, the API returns information about all categories in the {anomaly-job}.

`<job_id>`::
(Required, string)
include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]

[[ml-get-category-request-body]]
==== {api-request-body-title}

`page`.`from`::
(Optional, integer) Skips the specified number of categories.

`page`.`size`::
(Optional, integer) Specifies the maximum number of categories to obtain.

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

The API returns an array of category objects, which have the following
properties:

`category_id`::
(unsigned integer) A unique identifier for the category.

`examples`::
(array) A list of examples of actual values that matched the category.

`grok_pattern`::
experimental[] (string) A Grok pattern that could be used in {ls} or an ingest
pipeline to extract fields from messages that match the category. This field is
experimental and may be changed or removed in a future release. The Grok
patterns that are found are not optimal, but are often a good starting point for
manual tweaking.

`job_id`::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]

`max_matching_length`::
(unsigned integer) The maximum length of the fields that matched the category.
The value is increased by 10% to enable matching for similar fields that have
not been analyzed.

`regex`::
(string) A regular expression that is used to search for values that match the
category.

`terms`::
(string) A space separated list of the common tokens that are matched in values
of the category.

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

[source,console]
--------------------------------------------------
GET _ml/anomaly_detectors/esxi_log/results/categories
{
  "page":{
    "size": 1
  }
}
--------------------------------------------------
// TEST[skip:todo]

In this example, the API returns the following information:
[source,js]
----
{
  "count": 11,
  "categories": [
    {
      "job_id" : "esxi_log",
      "category_id" : 1,
      "terms" : "Vpxa verbose vpxavpxaInvtVm opID VpxaInvtVmChangeListener Guest DiskInfo Changed",
      "regex" : ".*?Vpxa.+?verbose.+?vpxavpxaInvtVm.+?opID.+?VpxaInvtVmChangeListener.+?Guest.+?DiskInfo.+?Changed.*",
      "max_matching_length": 154,
      "examples" : [
        "Oct 19 17:04:44 esxi1.acme.com Vpxa: [3CB3FB90 verbose 'vpxavpxaInvtVm' opID=WFU-33d82c31] [VpxaInvtVmChangeListener] Guest DiskInfo Changed",
        "Oct 19 17:04:45 esxi2.acme.com Vpxa: [3CA66B90 verbose 'vpxavpxaInvtVm' opID=WFU-33927856] [VpxaInvtVmChangeListener] Guest DiskInfo Changed",
        "Oct 19 17:04:51 esxi1.acme.com Vpxa: [FFDBAB90 verbose 'vpxavpxaInvtVm' opID=WFU-25e0d447] [VpxaInvtVmChangeListener] Guest DiskInfo Changed",
        "Oct 19 17:04:58 esxi2.acme.com Vpxa: [FFDDBB90 verbose 'vpxavpxaInvtVm' opID=WFU-bbff0134] [VpxaInvtVmChangeListener] Guest DiskInfo Changed"
      ],
      "grok_pattern" : ".*?%{SYSLOGTIMESTAMP:timestamp}.+?Vpxa.+?%{BASE16NUM:field}.+?verbose.+?vpxavpxaInvtVm.+?opID.+?VpxaInvtVmChangeListener.+?Guest.+?DiskInfo.+?Changed.*"
    }
  ]
}
----