OpenSearch/docs/en/rest-api/ml/get-category.asciidoc

//lcawley Verified example output 2017-04-11
[[ml-get-category]]
==== Get Categories

The get categories API enables you to retrieve information
about the categories in the results for a job.

===== Request

`GET _xpack/ml/anomaly_detectors/<job_id>/results/categories` +

`GET _xpack/ml/anomaly_detectors/<job_id>/results/categories/<category_id>`

===== Description

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
<<security-privileges>> and <<built-in-roles>>.

===== Path Parameters

`job_id`::
  (string) Identifier for the job.

`category_id`::
  (string) Identifier for the category. If you do not specify this optional parameter,
  the API returns information about all categories in the job.

===== Request Body

//TBD: Test these properties, since they didn't work on older build.

`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
    <<ml-results-categories,Categories>>.
////
===== Responses

200
(EmptyResponse) The cluster has been successfully deleted
404
(BasicFailedReply) The cluster specified by {cluster_id} cannot be found (code: clusters.cluster_not_found)
412
(BasicFailedReply) The Elasticsearch cluster has not been shutdown yet (code: clusters.cluster_plan_state_error)
////
===== Examples

The following example gets category information for the `it_ops_new_logs` job:

[source,js]
--------------------------------------------------
GET _xpack/ml/anomaly_detectors/it_ops_new_logs/results/categories
--------------------------------------------------
// CONSOLE
// TEST[skip:todo]

In this example, the API returns the following information for each category:
[source,js]
----
{
  "count": 11,
  "categories": [
    {
      "job_id": "it_ops_new_logs",
      "category_id": 1,
      "terms": "Actual Transaction Already Voided Reversed hostname
      dbserver.acme.com physicalhost esxserver1.acme.com vmhost app1.acme.com",
      "regex": ".*?Actual.+?Transaction.+?Already.+?Voided.+?Reversed.+?hostname.
      +?dbserver.acme.com.+?physicalhost.+?esxserver1.acme.com.+?vmhost.
      +?app1.acme.com.*",
      "max_matching_length": 137,
      "examples": [
        "Actual Transaction Already Voided / Reversed;hostname=dbserver.acme.com;
        physicalhost=esxserver1.acme.com;vmhost=app1.acme.com"
      ]
    },
  ...
  ]
}
----