OpenSearch/docs/reference/rollup/apis/get-job.asciidoc

[role="xpack"]
[testenv="basic"]
[[rollup-get-job]]
=== Get {rollup-jobs} API
++++
<titleabbrev>Get job</titleabbrev>
++++

Retrieves the configuration, stats, and status of {rollup-jobs}.

experimental[]

[[rollup-get-job-request]]
==== {api-request-title}

`GET _rollup/job/<job_id>`

[[rollup-get-job-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have `monitor`,
`monitor_rollup`, `manage` or `manage_rollup` cluster privileges to use this API.
For more information, see <<security-privileges>>.

[[rollup-get-job-desc]]
==== {api-description-title}

The API can return the details for a single {rollup-job} or for all {rollup-jobs}.

NOTE: This API returns only active (both `STARTED` and `STOPPED`) jobs. If a job
was created, ran for a while then deleted, this API does not return any details
about that job.

For details about a historical {rollup-job}, the
<<rollup-get-rollup-caps,rollup capabilities API>> may be more useful.

[[rollup-get-job-path-params]]
==== {api-path-parms-title}

`<job_id>`::
  (Optional, string) Identifier for the {rollup-job}. If it is `_all` or omitted,
   the API returns all {rollup-jobs}.

[role="child_attributes"]
[[rollup-get-job-response-body]]
==== {api-response-body-title}

`jobs`::
(array) An array of {rollup-job} resources. 
+
.Properties of {rollup-job} resources
[%collapsible%open]
====
`config`:::
(object) Contains the configuration for the {rollup-job}. This information is
identical to the configuration that was supplied when creating the job via the
<<rollup-put-job,create job API>>.

`stats`:::
(object) Contains transient statistics about the {rollup-job}, such as how many
documents have been processed and how many rollup summary docs have been
indexed. These stats are not persisted. If a node is restarted, these stats are
reset.

`status`:::
(object) Contains the current status of the indexer for the {rollup-job}. The
possible values and their meanings are:
+
- `stopped` means the indexer is paused and will not process data, even if its
cron interval triggers.
- `started` means the indexer is running, but not actively indexing data. When
the cron interval triggers, the job's indexer will begin to process data.
- `indexing` means the indexer is actively processing data and creating new
rollup documents. When in this state, any subsequent cron interval triggers will
be ignored because the job is already active with the prior trigger.
- `abort` is a transient state, which is usually not witnessed by the user. It
is used if the task needs to be shut down for some reason (job has been deleted,
an unrecoverable error has been encountered, etc).  Shortly after the `abort`
state is set, the job will remove itself from the cluster.
====

[[rollup-get-job-example]]
==== {api-examples-title}

If we have already created a rollup job named `sensor`, the details about the
job can be retrieved with:

[source,console]
--------------------------------------------------
GET _rollup/job/sensor
--------------------------------------------------
// TEST[setup:sensor_rollup_job]

The API yields the following response:

[source,console-result]
----
{
  "jobs": [
    {
      "config": {
        "id": "sensor",
        "index_pattern": "sensor-*",
        "rollup_index": "sensor_rollup",
        "cron": "*/30 * * * * ?",
        "groups": {
          "date_histogram": {
            "fixed_interval": "1h",
            "delay": "7d",
            "field": "timestamp",
            "time_zone": "UTC"
          },
          "terms": {
            "fields": [
              "node"
            ]
          }
        },
        "metrics": [
          {
            "field": "temperature",
            "metrics": [
              "min",
              "max",
              "sum"
            ]
          },
          {
            "field": "voltage",
            "metrics": [
              "avg"
            ]
          }
        ],
        "timeout": "20s",
        "page_size": 1000
      },
      "status": {
        "job_state": "stopped",
        "upgraded_doc_id": true
      },
      "stats": {
        "pages_processed": 0,
        "documents_processed": 0,
        "rollups_indexed": 0,
        "trigger_count": 0,
        "index_failures": 0,
        "index_time_in_ms": 0,
        "index_total": 0,
        "search_failures": 0,
        "search_time_in_ms": 0,
        "search_total": 0,
        "processing_time_in_ms": 0,
        "processing_total": 0
      }
    }
  ]
}
----

The `jobs` array contains a single job (`id: sensor`) since we requested a single job in the endpoint's URL.
If we add another job, we can see how multi-job responses are handled:

[source,console]
--------------------------------------------------
PUT _rollup/job/sensor2 <1>
{
  "index_pattern": "sensor-*",
  "rollup_index": "sensor_rollup",
  "cron": "*/30 * * * * ?",
  "page_size": 1000,
  "groups": {
    "date_histogram": {
      "field": "timestamp",
      "fixed_interval": "1h",
      "delay": "7d"
    },
    "terms": {
      "fields": [ "node" ]
    }
  },
  "metrics": [
    {
      "field": "temperature",
      "metrics": [ "min", "max", "sum" ]
    },
    {
      "field": "voltage",
      "metrics": [ "avg" ]
    }
  ]
}

GET _rollup/job/_all <2>
--------------------------------------------------
// TEST[setup:sensor_rollup_job]
<1> We create a second job with name `sensor2`
<2> Then request all jobs by using `_all` in the GetJobs API

Which will yield the following response:

[source,js]
----
{
  "jobs": [
    {
      "config": {
        "id": "sensor2",
        "index_pattern": "sensor-*",
        "rollup_index": "sensor_rollup",
        "cron": "*/30 * * * * ?",
        "groups": {
          "date_histogram": {
            "fixed_interval": "1h",
            "delay": "7d",
            "field": "timestamp",
            "time_zone": "UTC"
          },
          "terms": {
            "fields": [
              "node"
            ]
          }
        },
        "metrics": [
          {
            "field": "temperature",
            "metrics": [
              "min",
              "max",
              "sum"
            ]
          },
          {
            "field": "voltage",
            "metrics": [
              "avg"
            ]
          }
        ],
        "timeout": "20s",
        "page_size": 1000
      },
      "status": {
        "job_state": "stopped",
        "upgraded_doc_id": true
      },
      "stats": {
        "pages_processed": 0,
        "documents_processed": 0,
        "rollups_indexed": 0,
        "trigger_count": 0,
        "index_failures": 0,
        "index_time_in_ms": 0,
        "index_total": 0,
        "search_failures": 0,
        "search_time_in_ms": 0,
        "search_total": 0,
        "processing_time_in_ms": 0,
        "processing_total": 0
      }
    },
    {
      "config": {
        "id": "sensor",
        "index_pattern": "sensor-*",
        "rollup_index": "sensor_rollup",
        "cron": "*/30 * * * * ?",
        "groups": {
          "date_histogram": {
            "fixed_interval": "1h",
            "delay": "7d",
            "field": "timestamp",
            "time_zone": "UTC"
          },
          "terms": {
            "fields": [
              "node"
            ]
          }
        },
        "metrics": [
          {
            "field": "temperature",
            "metrics": [
              "min",
              "max",
              "sum"
            ]
          },
          {
            "field": "voltage",
            "metrics": [
              "avg"
            ]
          }
        ],
        "timeout": "20s",
        "page_size": 1000
      },
      "status": {
        "job_state": "stopped",
        "upgraded_doc_id": true
      },
      "stats": {
        "pages_processed": 0,
        "documents_processed": 0,
        "rollups_indexed": 0,
        "trigger_count": 0,
        "index_failures": 0,
        "index_time_in_ms": 0,
        "index_total": 0,
        "search_failures": 0,
        "search_time_in_ms": 0,
        "search_total": 0,
        "processing_time_in_ms": 0,
        "processing_total": 0
      }
    }
  ]
}
----
// NOTCONSOLE