> ## Documentation Index > Fetch the complete documentation index at: https://docs.cortex.io/llms.txt > Use this file to discover all available pages before exploring further. # Preview a retry of a failed workflow run > Show what a retry of a failed or timed-out run does: the actions that run again, and the actions that can change another system again. When the run cannot be retried, the response is 200 with `retryable` false, and `refusal` says why. This changes nothing. To retry, send `planVersion` to `retryWorkflowRun`. When `fromSlug` is not the failed action, also send the slug of each `CONFIRM` action. API key must have the `Run workflows` permission and the workflow must be runnable via API. ## OpenAPI ````yaml /openapi/cortex_swagger.json get /api/v1/workflows/{tagOrId}/runs/{runId}/retry-preview openapi: 3.0.1 info: description: >- The Cortex REST API provides programmatic access to the data in the catalog, Scorecards, and more. title: Cortex API version: v1 servers: - url: https://api.getcortexapp.com description: US (Cortex cloud) - url: https://api.eu.cortex.io description: EU (Cortex cloud) - url: '{baseUrl}' description: Self-managed variables: baseUrl: description: >- Your Cortex backend URL (the app.hostnames.backend value from your Helm chart) default: https://cortex-api.yourdomain.example security: - bearerAuth: [] tags: - name: API Keys - name: Audit Logs - name: Capability Health - name: Catalog Entities - name: Catalogs - name: Custom Data - name: Custom Data [Advanced] - name: Custom Events - name: Custom Metrics - name: Dependencies - name: Deploys - name: Discovery Audit - name: Docs - name: 'Eng Intel: 1-Registry' - name: 'Eng Intel: 2-Metrics' - name: 'Eng Intel: 3-Trace' - name: 'Eng Intel: User Labels' - name: Entity Archival - name: Entity Relationship Types - name: Entity Relationships - name: Entity Types - name: GitOps Logs - name: Groups - name: IP Allowlist - name: Initiatives - name: Integration Status - name: My Workspace - name: Notification Logs - name: On-call - name: Packages - name: Plugins - name: Queries - name: Recommendations - name: SCIM - name: SCIM Role Mappings - name: Scaffolder - name: Scorecards - name: Secrets - name: Team Roles - name: Teams - name: Teams Hierarchies - name: Teams [Advanced] - name: Teams [Departments] (legacy) - name: Users - name: Verifications - name: Workflows - name: '[Integrations] AWS' - name: '[Integrations] Anthropic' - name: '[Integrations] Apiiro' - name: '[Integrations] ArgoCD' - name: '[Integrations] Azure Active Directory' - name: '[Integrations] Azure Devops' - name: '[Integrations] Azure Resources' - name: '[Integrations] BambooHR' - name: '[Integrations] Bitbucket' - name: '[Integrations] Bugsnag' - name: '[Integrations] Buildkite' - name: '[Integrations] Checkmarx SAST' - name: '[Integrations] CircleCI' - name: '[Integrations] ClickUp' - name: '[Integrations] Codecov' - name: '[Integrations] Coralogix' - name: '[Integrations] Datadog' - name: '[Integrations] Dynatrace' - name: '[Integrations] Firehydrant' - name: '[Integrations] GitHub' - name: '[Integrations] GitLab' - name: '[Integrations] Harness' - name: '[Integrations] Incident.io' - name: '[Integrations] Instana' - name: '[Integrations] Jenkins' - name: '[Integrations] Jira' - name: '[Integrations] Kubernetes' - name: '[Integrations] LaunchDarkly' - name: '[Integrations] Lightstep' - name: '[Integrations] Mend SAST' - name: '[Integrations] Mend SCA' - name: '[Integrations] New Relic' - name: '[Integrations] Okta' - name: '[Integrations] Opsgenie' - name: '[Integrations] PagerDuty' - name: '[Integrations] Prometheus' - name: '[Integrations] Rollbar' - name: '[Integrations] Rootly' - name: '[Integrations] Semgrep' - name: '[Integrations] Sentry' - name: '[Integrations] ServiceNow' - name: '[Integrations] SignalFx' - name: '[Integrations] Snyk' - name: '[Integrations] SonarQube' - name: '[Integrations] SumoLogic' - name: '[Integrations] Veracode' - name: '[Integrations] VictorOps' - name: '[Integrations] Wiz' - name: '[Integrations] Workday' - name: '[Integrations] xMatters' - name: dev-login-controller - name: public-scim-schema-controller paths: /api/v1/workflows/{tagOrId}/runs/{runId}/retry-preview: get: tags: - Workflows summary: Preview a retry of a failed workflow run description: >- Show what a retry of a failed or timed-out run does: the actions that run again, and the actions that can change another system again. When the run cannot be retried, the response is 200 with `retryable` false, and `refusal` says why. This changes nothing. To retry, send `planVersion` to `retryWorkflowRun`. When `fromSlug` is not the failed action, also send the slug of each `CONFIRM` action. API key must have the `Run workflows` permission and the workflow must be runnable via API. operationId: previewWorkflowRunRetry parameters: - description: The tag or unique, auto-generated identifier for the workflow. in: path name: tagOrId required: true schema: type: string description: Entity identifier - can be a tag or CID - description: The ID of the failed run in: path name: runId required: true schema: type: string - description: >- The action to start the retry from. Defaults to the failed action. To start in a child run, use `/`. in: query name: fromSlug required: false schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/WorkflowRunRetryPreviewResponse' description: The retry plan, or why the run cannot be retried '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Access denied '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Workflow or run not found '429': $ref: '#/components/responses/TooManyRequests' components: schemas: WorkflowRunRetryPreviewResponse: required: - retryable type: object properties: plan: $ref: '#/components/schemas/WorkflowRunRetryPlan' planVersion: type: string description: >- Identifies this plan. Send it to the retry endpoint, which refuses the retry with `PLAN_CHANGED` when the plan is different. refusal: $ref: '#/components/schemas/WorkflowRunRetryRefusal' retryable: type: boolean description: >- True when the run can be retried. Then `plan` and `planVersion` are set. ErrorResponse: required: - message - type type: object properties: details: type: string errorCode: type: string gatewayHttpStatus: type: integer format: int32 httpStatus: type: integer format: int32 message: type: string requestId: type: string type: type: string enum: - INTEGRATION_MISSING - INTEGRATION_UNREGISTERED - INTEGRATION_UNSUPPORTED - INTEGRATION_GRAPHQL_ERROR - INTEGRATION_BAD_REQUEST - INTEGRATION_UNAUTHORIZED - INTEGRATION_FORBIDDEN - INTEGRATION_NOT_FOUND - INTEGRATION_UNPROCESSABLE_CONTENT - INTEGRATION_RATE_LIMITED - INTEGRATION_INTERNAL_ERROR - INTEGRATION_NOT_IMPLEMENTED - INTEGRATION_BAD_GATEWAY - INTEGRATION_UNAVAILABLE - INTEGRATION_GATEWAY_TIMEOUT - INTEGRATION_TIMED_OUT - INTEGRATION_CACHE_ERROR - INTEGRATION_UNHANDLED_HTTP_ERROR - INTEGRATION_UNHANDLED_EXCEPTION - INTEGRATION_UNEXPECTED_ERROR - ILLEGAL_ARGUMENT_ERROR - BAD_REQUEST - FORBIDDEN - NOT_FOUND - REQUEST_TIMEOUT - CONFLICT - UNHANDLED_EXCEPTION - UNCATEGORIZED - SERVICE_CREATOR - UNKNOWN_HOST - TOO_MANY_REQUESTS WorkflowRunRetryPlan: required: - actions - changedCarriedOverSlugs - failedAction - fromSlug - startSlugs type: object properties: actions: type: array description: >- The actions that the retry runs, in workflow order. Before a branch, it lists the actions of every branch. items: $ref: '#/components/schemas/WorkflowRunRetryPlanAction' changedCarriedOverSlugs: type: array description: >- Actions whose results the retry keeps, but whose settings changed since the failed run items: type: string description: >- Actions whose results the retry keeps, but whose settings changed since the failed run childRetry: $ref: '#/components/schemas/WorkflowRunRetryChildRetry' failedAction: $ref: '#/components/schemas/WorkflowRunRetryFailedAction' fromSlug: type: string description: The action that the retry starts from sourceInitiator: type: string description: The name of the user or API key that started the failed run sourceRunAs: type: string description: The name of the user that the failed run acted as startSlugs: type: array description: Every action that a retry can start from items: type: string description: Every action that a retry can start from description: The actions that the retry runs WorkflowRunRetryRefusal: required: - errorCode - httpStatus - message type: object properties: errorCode: type: string description: >- A stable code for the reason. The retry endpoint returns the same codes, and also `CONFIRMATION_REQUIRED` and `PLAN_CHANGED`. enum: - ACCESS_DENIED - HISTORY_NOT_FOUND - RUN_NOT_RETRYABLE - ALREADY_RETRIED - WAITED_ON_CHILD - RUN_CHECK_FAILED - CONFIRMATION_REQUIRED - PLAN_CHANGED - ACTION_NOT_FOUND - ACTION_CHANGED - ACTION_NOT_RETRYABLE - ACTION_ADDED_BEFORE_START - VARIABLE_TYPE_CHANGED httpStatus: type: integer description: The HTTP status that the retry endpoint returns for this refusal format: int32 message: type: string description: Why the run cannot be retried, for a person to read parentRunId: type: string description: For `WAITED_ON_CHILD`, the parent run to retry instead parentWorkflowCid: type: string description: For `WAITED_ON_CHILD`, the workflow of the parent run retriedByRunId: type: string description: For `ALREADY_RETRIED`, the run that retried this run slugs: type: array description: >- The action slugs that the refusal is about. For `VARIABLE_TYPE_CHANGED`, the names of the global variables. items: type: string description: >- The action slugs that the refusal is about. For `VARIABLE_TYPE_CHANGED`, the names of the global variables. description: Why the run cannot be retried. Set only when `retryable` is false. TooManyRequestsProblemDetail: required: - type - title - status type: object properties: detail: type: string instance: type: string format: uri-reference retryAfter: minimum: 0 type: integer description: The number of seconds until the rate limiting resets. format: int32 status: maximum: 599 minimum: 100 type: integer format: int32 enum: - 429 title: type: string type: type: string format: uri-reference WorkflowRunRetryPlanAction: required: - completedInSource - name - safety - slug type: object properties: completedInSource: type: boolean description: True when the action completed in the failed run name: type: string description: Name of the action reason: type: string description: Why a repeat can change something, for a person to read reasonCode: type: string description: A stable code for `reason` enum: - UNSPECIFIED - HTTP_WRITE - HTTP_ASYNC - AWS_WRITE - SCRIPT - MESSAGE - ISSUE_CREATE - INCIDENT_CREATE - WORKFLOW_RUN - SCAFFOLD - APPROVAL_REQUEST - GITHUB_COMMIT safety: type: string description: >- `SAFE` when a repeat changes nothing in another system. `CONFIRM` when a repeat can change something or message someone. When the retry does not start from the failed action, the retry request must list the slug in `acknowledgedSlugs`. enum: - SAFE - CONFIRM slug: type: string description: Slug of the action target: type: string description: What a repeat can change, for example a URL description: >- The actions that the retry runs, in workflow order. Before a branch, it lists the actions of every branch. WorkflowRunRetryChildRetry: required: - childRunId type: object properties: childRunId: type: string description: The failed child run childWorkflowCid: type: string description: The workflow of the child run newChildReason: type: string description: Why a new child run starts instead of a retry of the child plan: $ref: '#/components/schemas/WorkflowRunRetryPlan' description: >- Set when `fromSlug` is a Run Workflow action that waited for a child run. Confirm the child's actions as `/`. WorkflowRunRetryFailedAction: required: - name - slug type: object properties: errorMessage: type: string description: The error of the action name: type: string description: Name of the action outputs: type: object additionalProperties: $ref: '#/components/schemas/JsonNode' description: The outputs of the action. Secrets are hidden. slug: type: string description: Slug of the action description: The action that failed JsonNode: type: object responses: TooManyRequests: content: application/problem+json: schema: $ref: '#/components/schemas/TooManyRequestsProblemDetail' description: >- The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay. headers: Retry-After: description: The number of seconds until the rate limiting resets. schema: minimum: 0 type: integer format: int32 securitySchemes: bearerAuth: bearerFormat: JWT description: >- All requests to the Cortex API need to provide an `Authorization: Bearer ` header, where `` is an API key created in the Settings page of your workspace. scheme: bearer type: http ```` ## Related topics - [Retry a failed workflow run](https://docs.cortex.io/api/rest/workflows/retry-a-failed-workflow-run.md) - [Running a Workflow](https://docs.cortex.io/streamline/workflows/run.md) - [Cortex beta program and release phases](https://docs.cortex.io/resources/beta.md)