Stop Pipeline
Try it
POST
/v0/pipelines/{pipeline_name}/stopStop the pipeline asynchronously by updating the desired state.
There are two variants:
/stop?force=false(default): the pipeline will first atomically checkpoint before deprovisioning the compute resources. When resuming, the pipeline will start from this/stop?force=true: the compute resources will be immediately deprovisioned. When resuming, it will pick up the latest checkpoint made by the periodic checkpointer or by a prior/checkpointcall.
The endpoint returns immediately after setting the desired state to Suspended for
?force=false or Stopped for ?force=true. In the former case, once the pipeline has
successfully passes the Suspending state, the desired state will become Stopped as well.
The procedure to get to the desired state is performed asynchronously. Progress should be
monitored by polling the pipeline GET endpoints.
Note the following:
- The suspending that is done with
/stop?force=falseis not guaranteed to succeed: - If an error is returned during the suspension, the pipeline will be forcefully stopped with that error set
- Otherwise, it will keep trying to suspend, in which case it is possible to cancel suspending
by calling
/stop?force=true /stop?force=truecannot be cancelled: the pipeline must first reachStoppedbefore another action can be done- A pipeline which is in the process of suspending or stopping can only be forcefully stopped
Authentication
JSON web token (JWT) or API keyBearer token
Parameters
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
pipeline_name | string | Yes | Unique pipeline name |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
force | boolean | No | The `force` parameter determines whether to immediately deprovision the pipeline compute resources (`force=true`) or first attempt to atomically checkpoint before doing so (`force=false`, which is the default). |
Response
202Action is accepted and is being performed
400Action could not be performed
application/json- objectInformation returned by REST API endpoints on error.
detailsobjectrequiredDetailed error metadata. The contents of this field is determined by `error_code`.error_codestringrequiredError code is a string that specifies this error type.messagestringrequiredHuman-readable error message.
404Pipeline with that name does not exist
application/json- objectInformation returned by REST API endpoints on error.
detailsobjectrequiredDetailed error metadata. The contents of this field is determined by `error_code`.error_codestringrequiredError code is a string that specifies this error type.messagestringrequiredHuman-readable error message.
405Action is not supported
application/json- objectInformation returned by REST API endpoints on error.
detailsobjectrequiredDetailed error metadata. The contents of this field is determined by `error_code`.error_codestringrequiredError code is a string that specifies this error type.messagestringrequiredHuman-readable error message.
500
application/json- objectInformation returned by REST API endpoints on error.
detailsobjectrequiredDetailed error metadata. The contents of this field is determined by `error_code`.error_codestringrequiredError code is a string that specifies this error type.messagestringrequiredHuman-readable error message.
501Action is not implemented because it is only available in the Enterprise edition
application/json- objectInformation returned by REST API endpoints on error.
detailsobjectrequiredDetailed error metadata. The contents of this field is determined by `error_code`.error_codestringrequiredError code is a string that specifies this error type.messagestringrequiredHuman-readable error message.
503Action can not be performed (maybe because the pipeline is already suspended)
application/json- objectInformation returned by REST API endpoints on error.
detailsobjectrequiredDetailed error metadata. The contents of this field is determined by `error_code`.error_codestringrequiredError code is a string that specifies this error type.messagestringrequiredHuman-readable error message.
curl -X POST 'https://api.example.com/v0/pipelines/{pipeline_name}/stop?force=<force>' \
-H 'Authorization: Bearer YOUR_TOKEN'const response = await fetch('https://api.example.com/v0/pipelines/{pipeline_name}/stop?force=<force>', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
});
const data = await response.json();
console.log(data);interface ApiResponse {
// shape your response here
}
const response: Response = await fetch('https://api.example.com/v0/pipelines/{pipeline_name}/stop?force=<force>', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_TOKEN'
}
});
const data = (await response.json()) as ApiResponse;
console.log(data);import requests
url = "https://api.example.com/v0/pipelines/{pipeline_name}/stop"
params = {
"force": "<force>"
}
headers = {
"Authorization": "Bearer YOUR_TOKEN"
}
response = requests.request("post", url, params=params, headers=headers)
print(response.json())package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, err := http.NewRequest("POST", "https://api.example.com/v0/pipelines/{pipeline_name}/stop?force=<force>", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(string(out))
}{
"message": "Deployment resources status (current: 'Stopping', desired: 'Stopped') cannot have desired changed to 'Provisioned'. Cannot restart the pipeline while it is stopping. Wait for it to stop before starting a new instance of the pipeline.",
"error_code": "IllegalPipelineAction",
"details": {
"status": "Stopping",
"current_desired_status": "Stopped",
"new_desired_status": "Provisioned",
"hint": "Cannot restart the pipeline while it is stopping. Wait for it to stop before starting a new instance of the pipeline."
}
}{
"message": "Unknown pipeline name 'non-existent-pipeline'",
"error_code": "UnknownPipelineName",
"details": {
"pipeline_name": "non-existent-pipeline"
}
}