[role="xpack"]
[[ml-get-category]]
=== Get Categories API
++++
Get Categories
++++
Retrieves job results for one or more categories.
==== Request
`GET _xpack/ml/anomaly_detectors//results/categories` +
`GET _xpack/ml/anomaly_detectors//results/categories/`
==== Description
For more information about categories, see
{xpack-ref}/ml-configuring-categories.html[Categorizing Log Messages].
//<>.
==== Path Parameters
`job_id`::
(string) Identifier for the job.
`category_id`::
(long) Identifier for the category. If you do not specify this optional parameter,
the API returns information about all categories in the job.
==== Request Body
`page`::
`from`:::
(integer) Skips the specified number of categories.
`size`:::
(integer) Specifies the maximum number of categories to obtain.
==== Results
The API returns the following information:
`categories`::
(array) An array of category objects. For more information, see
<>.
==== Authorization
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. For more information, see
{xpack-ref}/security-privileges.html[Security Privileges] and
{xpack-ref}/built-in-roles.html[Built-in Roles].
//<> and <>.
==== Examples
The following example gets information about one category for the
`esxi_log` job:
[source,js]
--------------------------------------------------
GET _xpack/ml/anomaly_detectors/esxi_log/results/categories
{
"page":{
"size": 1
}
}
--------------------------------------------------
// CONSOLE
// 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.*"
}
]
}
----