---
title: "Simulate a workflow"
method: POST
path: "/workflows/dry-run"
tags: ["Workflows"]
---

# Simulate a workflow

`POST /workflows/dry-run`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/workflows/dry-run`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

Walk a definition over imaginary creators for `days` simulated days and return each one's path, the messages they would have received, and per-step counts. Nothing is written and nothing is sent. Supply `scenario.creators` to script specific attributes and events, or omit it for a default cast.

## Request body

- WorkflowDryRunBody
  - `definition` object, required: The workflow document: `name`, a `trigger` and its `steps`. Validated strictly on the way in. GET /workflows/templates returns working examples, GET /workflows/conditions the rule vocabulary for this shop, and POST /workflows/validate reports what is wrong with one.
  - `settings` object, nullable: Exclusions (`groups`, `lists`, `blacklist`), `dailyMessageLimits` and `dailyInviteLimits` keyed by weekday, `skipCreatorsInOtherWorkflows`, and `timezone` — which decides when the daily budget resets.
  - `scenario` object, nullable: `{"creators": [{name, attributes, events}]}` to script the cast, up to 50. Omit for a default cast of imaginary creators.
  - `days` integer: Simulated days to walk.
  - `tick_hours` integer: Simulated hours between runtime ticks.

## Response `200`

Successful Response

- EnvelopeWorkflowDryRunPublic
  - `data` WorkflowDryRunPublic, required
    - `days` integer, required
    - `entered` integer, required
    - `creators` WorkflowDryRunCreatorPublic[], required
      - `creator_id` string, required
      - `name` string, required
      - `final_state` string, required
      - `final_step` string, nullable
      - `exit_reason` string, nullable
      - `trace` object[], required
      - `truncated` boolean
      - `messages` object[], required: What this creator would have been sent. Nothing was sent.
    - `step_counts` object, required
    - `validation` WorkflowValidationPublic, required
      - `ok` boolean, required: No blocking issues. Warnings may still be present.
      - `blocking` integer, required: Issues that make `publish` refuse.
      - `warnings` integer, required
      - `issues` WorkflowValidationIssuePublic[], required
        - `step_id` string, required: Step id, or 'trigger', or 'workflow' for a graph-level issue.
        - `severity` string, required: blocking or warning.
        - `message` string, required
        - `field` string, nullable

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-10-20** `9353ed4982e8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/workflows/dry-run/post.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)