Retry a failed workflow run

curl --request POST \
  --url https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "acknowledgedSlugs": [
    "<string>"
  ],
  "planVersion": "<string>",
  "fromSlug": "<string>",
  "notificationRecipients": [
    "<string>"
  ],
  "runAs": "<string>"
}
'

import requests

url = "https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry"

payload = {
    "acknowledgedSlugs": ["<string>"],
    "planVersion": "<string>",
    "fromSlug": "<string>",
    "notificationRecipients": ["<string>"],
    "runAs": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    acknowledgedSlugs: ['<string>'],
    planVersion: '<string>',
    fromSlug: '<string>',
    notificationRecipients: ['<string>'],
    runAs: '<string>'
  })
};

fetch('https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'acknowledgedSlugs' => [
        '<string>'
    ],
    'planVersion' => '<string>',
    'fromSlug' => '<string>',
    'notificationRecipients' => [
        '<string>'
    ],
    'runAs' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry"

	payload := strings.NewReader("{\n  \"acknowledgedSlugs\": [\n    \"<string>\"\n  ],\n  \"planVersion\": \"<string>\",\n  \"fromSlug\": \"<string>\",\n  \"notificationRecipients\": [\n    \"<string>\"\n  ],\n  \"runAs\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"acknowledgedSlugs\": [\n    \"<string>\"\n  ],\n  \"planVersion\": \"<string>\",\n  \"fromSlug\": \"<string>\",\n  \"notificationRecipients\": [\n    \"<string>\"\n  ],\n  \"runAs\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"acknowledgedSlugs\": [\n    \"<string>\"\n  ],\n  \"planVersion\": \"<string>\",\n  \"fromSlug\": \"<string>\",\n  \"notificationRecipients\": [\n    \"<string>\"\n  ],\n  \"runAs\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "actions": [
    {
      "isRootAction": true,
      "name": "<string>",
      "outgoingActions": [
        "<string>"
      ],
      "schema": {
        "headers": {},
        "httpMethod": "GET",
        "type": "HTTP_REQUEST",
        "url": "<string>",
        "integration": "AzureDevops",
        "integrationAlias": "<string>",
        "payload": "<string>",
        "targetHost": "<string>"
      },
      "slug": "<string>",
      "state": {
        "status": "NOT_INITIATED",
        "inputs": {},
        "metadata": {},
        "outputs": {},
        "variables": {}
      },
      "carriedOver": {
        "runId": "<string>",
        "completedAt": "<string>",
        "startedAt": "<string>"
      },
      "completedAt": "<string>",
      "startedAt": "<string>"
    }
  ],
  "id": "<string>",
  "status": "NOT_INITIATED",
  "variables": {},
  "workflow": {
    "cid": "<string>",
    "name": "<string>"
  },
  "completedAt": "<string>",
  "context": {},
  "initiatedBy": {
    "type": "<string>",
    "apiKey": {
      "id": "<string>",
      "last4": "<string>",
      "type": "<string>",
      "name": "<string>"
    }
  },
  "retriedByRunId": "<string>",
  "retryOfRunId": "<string>",
  "runResponse": "<string>",
  "startedAt": "<string>"
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "status": 429,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "retryAfter": 1
}

Retry a failed workflow run

Start a new run that retries a failed or timed-out run. The new run keeps the results of the actions before the start action and runs the rest again. The failed run does not change.

First call previewWorkflowRunRetry, and send its planVersion. When fromSlug is not the failed action, also list in acknowledgedSlugs the slug of each action that has the CONFIRM safety level.

The retry never copies runAs from the failed run. Send runAs again when the retry must act as a user. If the retry pauses at a user input or scaffolder action, a user must fill in the form in Cortex.

API key must have the Run workflows permission and the workflow must be runnable via API.

A refused retry returns errorCode with one of these values:

Code	Status	Meaning
`ACCESS_DENIED`	403	The caller cannot view the run.
`HISTORY_NOT_FOUND`	404	The history of the run is gone or too old.
`RUN_NOT_RETRYABLE`	409	The run did not fail or time out, has no failed action, or an approver rejected it.
`ALREADY_RETRIED`	409	Another run already retried this run. Retry the run in `retriedByRunId`.
`WAITED_ON_CHILD`	409	A parent run waited for this run. Retry the run in `parentRunId`.
`RUN_CHECK_FAILED`	400, 403, 404 or 429	A check that a new run must pass failed, for example the workflow is not runnable via API. The status is the one that a new run gets.
`CONFIRMATION_REQUIRED`	409	The retry does not start from the failed action, and `acknowledgedSlugs` does not list each action in `slugs`.
`PLAN_CHANGED`	409	The workflow or the run changed after the preview. Preview the retry again.
`ACTION_NOT_FOUND`	422	The start action, or an action whose result the retry keeps, is not in the latest version of the workflow.
`ACTION_CHANGED`	422	An action whose result the retry keeps has a different type in the latest version.
`ACTION_NOT_RETRYABLE`	422	The start action did not run in the failed run.
`ACTION_ADDED_BEFORE_START`	422	New actions lead into the start action. Retry from an action before them.
`VARIABLE_TYPE_CHANGED`	422	A global variable in `slugs` changed its type.

POST

api

workflows

{tagOrId}

runs

{runId}

retry

Retry a failed workflow run

curl --request POST \
  --url https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "acknowledgedSlugs": [
    "<string>"
  ],
  "planVersion": "<string>",
  "fromSlug": "<string>",
  "notificationRecipients": [
    "<string>"
  ],
  "runAs": "<string>"
}
'

import requests

url = "https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry"

payload = {
    "acknowledgedSlugs": ["<string>"],
    "planVersion": "<string>",
    "fromSlug": "<string>",
    "notificationRecipients": ["<string>"],
    "runAs": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    acknowledgedSlugs: ['<string>'],
    planVersion: '<string>',
    fromSlug: '<string>',
    notificationRecipients: ['<string>'],
    runAs: '<string>'
  })
};

fetch('https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'acknowledgedSlugs' => [
        '<string>'
    ],
    'planVersion' => '<string>',
    'fromSlug' => '<string>',
    'notificationRecipients' => [
        '<string>'
    ],
    'runAs' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry"

	payload := strings.NewReader("{\n  \"acknowledgedSlugs\": [\n    \"<string>\"\n  ],\n  \"planVersion\": \"<string>\",\n  \"fromSlug\": \"<string>\",\n  \"notificationRecipients\": [\n    \"<string>\"\n  ],\n  \"runAs\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"acknowledgedSlugs\": [\n    \"<string>\"\n  ],\n  \"planVersion\": \"<string>\",\n  \"fromSlug\": \"<string>\",\n  \"notificationRecipients\": [\n    \"<string>\"\n  ],\n  \"runAs\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getcortexapp.com/api/v1/workflows/{tagOrId}/runs/{runId}/retry")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"acknowledgedSlugs\": [\n    \"<string>\"\n  ],\n  \"planVersion\": \"<string>\",\n  \"fromSlug\": \"<string>\",\n  \"notificationRecipients\": [\n    \"<string>\"\n  ],\n  \"runAs\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "actions": [
    {
      "isRootAction": true,
      "name": "<string>",
      "outgoingActions": [
        "<string>"
      ],
      "schema": {
        "headers": {},
        "httpMethod": "GET",
        "type": "HTTP_REQUEST",
        "url": "<string>",
        "integration": "AzureDevops",
        "integrationAlias": "<string>",
        "payload": "<string>",
        "targetHost": "<string>"
      },
      "slug": "<string>",
      "state": {
        "status": "NOT_INITIATED",
        "inputs": {},
        "metadata": {},
        "outputs": {},
        "variables": {}
      },
      "carriedOver": {
        "runId": "<string>",
        "completedAt": "<string>",
        "startedAt": "<string>"
      },
      "completedAt": "<string>",
      "startedAt": "<string>"
    }
  ],
  "id": "<string>",
  "status": "NOT_INITIATED",
  "variables": {},
  "workflow": {
    "cid": "<string>",
    "name": "<string>"
  },
  "completedAt": "<string>",
  "context": {},
  "initiatedBy": {
    "type": "<string>",
    "apiKey": {
      "id": "<string>",
      "last4": "<string>",
      "type": "<string>",
      "name": "<string>"
    }
  },
  "retriedByRunId": "<string>",
  "retryOfRunId": "<string>",
  "runResponse": "<string>",
  "startedAt": "<string>"
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "errorCode": "ACCESS_DENIED",
  "httpStatus": 123,
  "message": "<string>",
  "type": "INTEGRATION_MISSING",
  "parentRunId": "<string>",
  "parentWorkflowCid": "<string>",
  "parentWorkflowId": 123,
  "requestId": "<string>",
  "retriedByRunId": "<string>",
  "slugs": [
    "<string>"
  ]
}

{
  "status": 429,
  "title": "<string>",
  "type": "<string>",
  "detail": "<string>",
  "instance": "<string>",
  "retryAfter": 1
}

Authorizations

Authorization

string

header

required

All requests to the Cortex API need to provide an Authorization: Bearer <token> header, where <token> is an API key created in the Settings page of your workspace.

Path Parameters

tagOrId

string

required

The tag or unique, auto-generated identifier for the workflow. Entity identifier - can be a tag or CID

runId

string

required

The ID of the failed run

Query Parameters

includeContext

boolean

When true, the response includes the run context. Defaults to false for MCP clients and true otherwise.

Body

application/json

acknowledgedSlugs

string[]

required

The slug of each action that has the CONFIRM safety level in the preview. This confirms that the action can run again. Not needed when the retry starts from the failed action.

planVersion

string

required

The planVersion from the preview

fromSlug

string

The action to start the retry from. Defaults to the failed action. Use the same value as in the preview.

notificationRecipients

string[]

User IDs or email addresses to notify of the retry's updates, not both. When left out, the retry notifies the recipients of the failed run. An empty list notifies nobody.

runAs

string

Email of the user that the retry acts as. The retry never copies it from the failed run.

Response

The new run started

actions

object[]

required

Actions and their states

Show child attributes

string

required

Id of the run

status

enum<string>

required

Status of the workflow run. PAUSED means it waits for a user input or an approval.

Available options:

NOT_INITIATED,

IN_PROGRESS,

PAUSED,

COMPLETED,

FAILED,

CANCELLED,

TIMED_OUT

variables

object

required

Variable values

Show child attributes

workflow

object

required

Summary of the workflow

Show child attributes

completedAt

string

Time the workflow run completed

context

object

Context of the run. Omitted when the request sets includeContext=false, which is the default for MCP clients.

Show child attributes

initiatedBy

object

Who initiated the workflow run

Option 1
Option 2

Show child attributes

retriedByRunId

string

Id of the run that retried this run. Null when no run retried it.

retryOfRunId

string

Id of the failed run that this run retries. Null when this run is not a retry.

runResponse

string

startedAt

string

Time the workflow run started

Get started

REST API operations

Retry a failed workflow run

Authorizations

Path Parameters

Query Parameters

Body

Response