---
title: "Preview edited DAG-run retry"
method: POST
path: "/dag-runs/{name}/{dagRunId}/edit-retry/preview"
tags: ["dag-runs"]
---

# Preview edited DAG-run retry

`POST /dag-runs/{name}/{dagRunId}/edit-retry/preview`

Validates an edited DAG definition against a previous DAG-run and returns the default step skip selection.

## Path parameters

- `name` string, regex, required — Name of the DAG
- `dagRunId` string, required — Unique identifier for the DAG-run. The special value 'latest' can be used to reference the most recent DAG-run.

## Query parameters

- `remoteNode` string

## Request body

- object
  - `spec` string, required — Edited DAG specification in YAML format.
  - `dagName` string — Optional DAG name override for the edited retry run.

## Response `200`

Successfully previewed the edited retry

- object
  - `dagName` string, required — Resolved DAG name for the edited retry.
  - `skippedSteps` string[], required — Default steps selected to be skipped.
  - `runnableSteps` string[], required — Steps that will be started if not skipped.
  - `steps` Step[], required — Resolved edited DAG steps in execution order for preview rendering.
    - `name` string, required — Unique identifier for the step within the DAG-run
    - `id` string — Optional short identifier for the step. Can be used in variable references like ${id.stdout} to access step properties. Must be unique within the DAG if specified
    - `description` string — Human-readable description of what the step does
    - `dir` string — Working directory for executing the step's command
    - `commands` CommandEntry[] — List of commands to execute sequentially
      - `command` string, required — The command to execute
      - `args` string[] — Arguments for the command
    - `script` string — Script content if the step executes a script file
    - `stdout` string — File path for capturing standard output
    - `stderr` string — File path for capturing standard error
    - `output` string — Variable name to store the step's output
    - `outputs` StepOutputDeclaration[] — Declared file-based step outputs published through DAGU_OUTPUT_FILE for ${steps.<id>.outputs.<name>} references. Steps that declare outputs must also define id.
      - `name` string, required — Published output name scoped to the declaring step
      - `type` 'string' | 'json' — Output value type. JSON outputs must contain valid JSON text.
    - `call` string — The name of the DAG to execute as a sub DAG-run
    - `params` string — Parameters to pass to the sub DAG-run in JSON format
    - `parallel` object — Configuration for parallel execution of the step
      - `items` union — Array of items to process in parallel. Can be a static array or a reference to a variable containing an array
        - string[]
        - string
      - `maxConcurrent` integer — Maximum number of parallel executions. Default is 10 if not specified
    - `depends` string[] — List of step names that must complete before this step can start
    - `repeatPolicy` RepeatPolicy — Configuration for step repeat behavior
      - `repeat` 'while' | 'until' — Repeat execution mode for steps
      - `interval` integer — Time in seconds to wait between repeat attempts
      - `limit` integer — Maximum number of times to repeat the step
      - `backoff` union
        - boolean — When true, uses default multiplier of 2.0
        - number, float — Custom exponential backoff multiplier
      - `maxIntervalSec` integer — Maximum interval in seconds (caps exponential growth)
      - `condition` Condition — Precondition that must be satisfied before running a step or DAG-run
        - `condition` string, required — Expression or check to evaluate. When `expected` is omitted, the value runs as a command check using the same variable expansion rules as shell `command` steps.
        - `expected` string — Expected result of the condition evaluation. When set, Dagu compares the evaluated string output instead of using command exit status.
        - `negate` boolean — If true, inverts the condition result (run when condition does NOT match)
        - `error` string — Error message if the condition is not met
        - `matched` boolean — Whether the condition was met
      - `exitCode` integer[] — List of exit codes that trigger repeat behavior
    - `mailOnError` boolean — Whether to send email notifications on step failure
    - `preconditions` Condition[] — Conditions that must be met before the step can start
      - `condition` string, required — Expression or check to evaluate. When `expected` is omitted, the value runs as a command check using the same variable expansion rules as shell `command` steps.
      - `expected` string — Expected result of the condition evaluation. When set, Dagu compares the evaluated string output instead of using command exit status.
      - `negate` boolean — If true, inverts the condition result (run when condition does NOT match)
      - `error` string — Error message if the condition is not met
      - `matched` boolean — Whether the condition was met
    - `timeoutSec` integer — Maximum execution time for the step in seconds. If set, this timeout takes precedence over the DAG-level timeout for this step.
    - `executorConfig` object — Executor configuration for this step
      - `type` string — Type of executor (e.g., 'wait', 'http', 'docker', 'command')
      - `config` object — Executor-specific configuration
    - `router` object — Router configuration for switch/case routing
      - `value` string, required — Expression to evaluate (e.g., '${STATUS}')
      - `routes` object[], required
        - `pattern` string, required — Match pattern (exact or 're:regex')
        - `targets` string[], required — Step names to route to
    - `approval` ApprovalConfig — Configuration for a human approval gate on a step
      - `prompt` string — Message displayed to the approver
      - `input` string[] — List of expected input field names from the approver
      - `required` string[] — Subset of input fields that must be provided
      - `rewindTo` string — Optional step name to restart from when the approver pushes the step back. Must reference the step itself or an upstream dependency.
  - `ineligibleSteps` object[], required — Previous completed steps that cannot be skipped with the edited specification.
    - `stepName` string, required
    - `reason` string, required
  - `errors` string[], required — Validation errors that must be fixed before launching.
  - `warnings` string[], required — Non-blocking warnings for the edited retry.

## Other responses

- `default` — Generic error response

## Changes

- **2026-06-18** (v1) `162df20bbef8` — 1 info
  - added the optional property `steps/items/outputs` to the response with the `200` status
- **2026-05-24** (v1) `8a2d5d3e9608` — 1 warning
  - added the new `rate_limited` enum value to the `code` response property for the response status `default`
- **2026-04-30** (v1) `50e1d517afc1` — 3 warning, 3 info
  - removed the optional property `steps/items/outputs` from the response with the `200` status
  - removed the optional property `steps/items/preconditions/items/eval` from the response with the `200` status
  - removed the optional property `steps/items/repeatPolicy/condition/eval` from the response with the `200` status
  - the response property `steps/items/preconditions/items/condition` became required for the status `200`
  - …2 more

[Change history](https://skmtc.dev/dagucloud/apis/dagu/changes/dag-runs/:name/:dagRunId/edit-retry/preview/post.md)

---

[API](https://skmtc.dev/dagucloud/apis/dagu.md) · [All operations](https://skmtc.dev/dagucloud/apis/dagu/llms.txt) · [OpenAPI document](https://skmtc.dev/dagucloud/apis/dagu/revisions/c5b8d495669e?raw)