Understanding workflow runs A workflow run represents a single execution triggered by an event and tracked from start to completion. Run states | State | Description | | ------------------------- | -------------------------------------------------------------------------------- | | **Pending** | Waiting for execution resources | | **Running** | Actively processing workflow steps | | **Completed** | All steps finished successfully | | **Completed with errors** | Run reached the end of the workflow, but at least one step errored along the way | | **Failed** | The run halted because a step encountered an unrecoverable error | | **Cancelled** | Execution stopped manually or by system | Run details Each run captures start time, duration, trigger context and inputs, step-by-step execution results, success and failure counts, and error messages. Access workflow run history from the workflow detail page. Filter by status, search by trigger data or time range, and sort by execution time or duration. *** Step-by-step logging Each workflow step is individually tracked with detailed execution information: * **Input values**: Raw and resolved inputs for the step * **Output data**: Data produced by the step * **AI reasoning**: For AI steps (Decision Maker, Custom Prompt), the explanation the model provided for its decision or response * **Execution duration**: How long the step took * **Error messages**: Details if the step failed * **Dynamic value resolution**: How references resolved at runtime Use step logs to trace how data flows through your workflow. See how trigger data passes to actions, how action outputs feed subsequent steps, and where values transform along the way. *** Performance monitoring Monitor executions per day, average duration, and peak usage periods Track completion rates and identify reliability trends Monitor error patterns and failure rates over time View processing times and identify performance bottlenecks *** Debugging workflows Check execution logs for specific error details and context Identify which step failed and review its inputs and outputs Verify data flowing between steps matches expectations Confirm external services are available and authenticated Make corrections in draft mode and test before republishing *** Common issues * Verify the workflow is published and active (not draft or paused) * Review trigger filters to confirm they match the expected event * Check that required integrations are connected * Check execution logs for the specific error message * Verify all required fields are populated * Test dynamic references with a manual run * Confirm integration permissions are correct and the external service is operational * Review dynamic value configuration for wrong references * Check trigger data structure in logs to confirm expected fields exist * Verify field names match exactly * Check for external API delays in step durations * Consider parallelizing sequential actions where possible * Review external service performance *** Error types | Error type | Cause | Fix | | --------------- | ------------------------------------------------------------- | ----------------------------------------------------------- | | **Validation** | Missing required fields, invalid formats, type mismatches | Review field requirements and provide valid data | | **Integration** | Connection timeouts, authentication failures, API rate limits | Check integration status and external service health | | **Permission** | Missing API scopes, insufficient access rights | Grant necessary permissions in integration settings | | **Timeout** | External API delays, large data processing, network issues | Optimize the workflow or check external service performance | *** Retrying workflow runs Retry a workflow run directly from the run history table when a run finishes in a state you want to redo. Use retries to recover from transient failures, rerun a workflow against the latest configuration, or re-execute a successful run on demand. When retry is available The **Retry** action appears in the row actions menu for any run with one of these statuses: * **Failed** * **Completed with errors** * **Completed** Pending, running, cancelled, and skipped runs cannot be retried. Retry options Selecting **Retry** opens a dialog with up to three options. Which options appear depends on the run’s status and whether a newer workflow version has been published since the run started. | Option | When it appears | What it does | | ------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **Retry with latest version** / **Rerun with latest version** | The run used an older workflow version and a newer version has been published | Starts a new run from the first step using the workflow’s current active version | | **Retry from failure** | The run failed or completed with errors and contains at least one failed step | Creates a new run that reuses successful upstream step outputs and reruns the failed step(s) on the same version | | **Retry from beginning** / **Rerun** | Always available for retryable runs | Starts a new run from the first step using the same workflow version as the original run | **Retry from failure** requires that the workflow shape upstream of the failed step has not changed between versions. If upstream steps were added, removed, or reconfigured, select **Retry with latest version** or **Retry from beginning** instead. Retry a run Navigate to the workflow and select the **Runs** tab Locate the run in the table. Filter by status if needed Hover the row and select **Retry** from the actions menu Select the option that matches your goal, then select **Retry** A new run appears in the table linked to the original as its parent. Open it to monitor execution Retry via API You can also retry a run programmatically. Send a `POST` request to `/workflows/runs/{runId}/retry` with an optional `versionId` and `retryFromFailure` flag. ```bash theme={"dark"} curl -X POST https://api.ravenna.ai/workflows/runs/{runId}/retry \ -H "Authorization: Bearer $RAVENNA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "versionId": "wfv_abc123", "retryFromFailure": true }' ``` | Field | Type | Description | | ------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `versionId` | string (optional) | Workflow version to run. Defaults to the version used by the original run. Pass the workflow’s active version ID to retry against the latest published version | | `retryFromFailure` | boolean (optional) | When `true`, reuses outputs from successful upstream steps and reruns failed step(s). When omitted or `false`, the run starts from the first step | The response contains the new `runId`. Use it to fetch the new run or display it in your tooling. *** Workflow attribution in tickets Each ticket event log shows which workflow triggered the change, including the workflow name, run ID, timestamp, and changed field values. Click the workflow badge on any ticket event to open the workflow run in a new tab and inspect the full run details. Use this to trace any automated update back to its source workflow. Workflow attribution helps you debug unexpected ticket changes, understand automation impact, and meet compliance requirements. *** Log management Workflow logs are retained for analysis and compliance. Run logs use a standard retention period, while error logs have extended retention. Export logs before the retention period expires if you need long-term storage. Log access is controlled by user permissions. View logs for workflows you own or manage. Workspace administrators can see all workflow logs. *** Failure notifications Configure notifications to receive alerts when workflow runs fail. Set up notifications from the workflow **Settings** tab. Failure notifications fire when a run finishes in either **Failed** or **Completed with errors**. The notification copy adapts to the run’s final status so recipients can tell at a glance whether the workflow halted entirely or completed end-to-end with at least one step error. Subscribe to email notifications for workflows you manage to receive personal failure alerts Configure Slack channels to notify entire teams when critical workflows fail Configuring failure notifications Navigate to your workflow and select the **Settings** tab Toggle **Email me on failures** to receive personal email alerts when the workflow fails Connect a Slack channel to post team notifications when workflow runs fail Trigger a test failure to verify notifications are delivered correctly Email notifications Personal email alerts notify you when workflows encounter failures. Each email includes the workflow name, run ID, and a direct link to the failure details. The subject line and body reflect whether the run **failed** or **completed with errors**. Emails include a one-click unsubscribe link that requires no authentication. **Use email notifications when:** * You need personal alerts for critical workflows * You want offline notification access * You manage workflows requiring immediate attention Slack notifications Team Slack notifications post failure alerts to channels where your team collaborates. Messages include Block Kit formatting with clickable buttons and a direct link to run details. The message header reads **Workflow Run Failed** or **Workflow Run Completed With Errors** depending on the run’s final status. **Use Slack notifications when:** * Teams need collective awareness of failures * Failures require coordinated response * Multiple people share responsibility for workflow reliability Email and Slack notifications work independently. You can enable both to ensure critical workflow failures reach your team through multiple channels. Unsubscribing from emails Workflow failure emails include a one-click unsubscribe link at the bottom. To resubscribe, visit the workflow **Settings** tab and toggle email notifications back on. Unsubscribe links are unique to each user and workflow. Clicking an unsubscribe link only affects your notifications for that specific workflow. *** Tips * **Set up failure notifications early.** Configure email and Slack alerts before relying on a workflow in production. * **Review error patterns regularly.** Look for increasing failure rates or performance degradation that might indicate systemic issues. * **Test after changes.** Monitor the first few executions closely after updating a workflow. * **Keep integrations healthy.** Refresh credentials before they expire and verify API permissions when integrations add new features. * **Document resolved issues.** Keep notes on what went wrong and how you fixed it. This helps troubleshoot similar problems faster next time. Learn more about [building workflows](/documentation/automate/workflows/workflow-builder) and [publishing workflows](/documentation/automate/workflows/publish)

Documentation Index