[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.*" } ] } ----