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

[role="xpack"]
[testenv="basic"]
[[rollup-stop-job]]
=== Stop {rollup-jobs} API
[subs="attributes"]
++++
<titleabbrev>Stop {rollup-jobs}</titleabbrev>
++++

Stops an existing, started {rollup-job}.

experimental[]

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

`POST _rollup/job/<job_id>/_stop`

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

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

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

If you try to stop a job that does not exist, an exception occurs. If you try
to stop a job that is already stopped, nothing happens.

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

`<job_id>`::
  (Required, string) Identifier for the {rollup-job}.

[[rollup-stop-job-query-parms]]
==== {api-query-parms-title}

`timeout`::
  (Optional, TimeValue) If `wait_for_completion` is `true`, the API blocks for
  (at maximum) the specified duration while waiting for the job to stop. If more
  than `timeout` time has passed, the API throws a timeout exception. Defaults
  to `30s`.
+
--
NOTE: Even if a timeout exception is thrown, the stop request is still
processing and eventually moves the job to `STOPPED`. The timeout simply means
the API call itself timed out while waiting for the status change.

--
  
`wait_for_completion`::
  (Optional, boolean) If set to `true`, causes the API to block until the
  indexer state completely stops. If set to `false`, the API returns immediately
  and the indexer is stopped asynchronously in the background. Defaults to
  `false`.

[[rollup-stop-job-response-codes]]
==== {api-response-codes-title}

`404` (Missing resources)::
  This code indicates that there are no resources that match the request. It
  occurs if you try to stop a job that doesn't exist.

[[rollup-stop-job-examples]]
==== {api-examples-title}

Since only a stopped job can be deleted, it can be useful to block the API until
the indexer has fully stopped. This is accomplished with the
`wait_for_completion` query parameter, and optionally a `timeout`:


[source,console]
--------------------------------------------------
POST _rollup/job/sensor/_stop?wait_for_completion=true&timeout=10s
--------------------------------------------------
// TEST[setup:sensor_started_rollup_job]

The parameter blocks the API call from returning until either the job has moved
to `STOPPED` or the specified time has elapsed. If the specified time elapses
without the job moving to `STOPPED`, a timeout exception is thrown.