📘 Definition

The "List Flow Runs" action in Zenphi allows you to retrieve a filtered list of all flow run instances within your current workspace. A flow run is an execution of a flow — each time a flow is triggered (manually or automatically), it creates a run with its own metadata (status, timestamps, initiator, etc.).

With this action, you can specify filters such as flow ID, status, and a date range, helping you narrow down the runs you're interested in. It’s especially useful for reporting, troubleshooting, or auditing purposes. The action supports pagination so that large sets of data can be navigated efficiently.

🔑 Key Capabilities

Retrieve execution history for a specific flow or all flows.
Filter runs by execution status, start/end dates, or specific flows.
Use pagination to handle large datasets with ease.
Access valuable metadata like initiator, version, and run duration.

Example Use Cases

1. Generate Flow Run Reports

Quickly fetch all runs of a particular flow over a defined time period to generate internal reports on automation performance, frequency, or outcomes.

2. Monitor Failed Runs

Filter and list only flow runs with the "faulted" or "faulted resume next" status to identify and troubleshoot flows that did not complete successfully.

3. Audit Flow Initiators

Retrieve the email addresses of users who triggered flows to audit who is starting which processes and when — useful for accountability and access control.

4. Analyze Execution Trends

Use the action to extract flow run data (status, start/finish time, etc.) for visualization in dashboards or external analytics tools to track process trends over time.

5. Validate Conditional Triggers

Check for runs with the "skipped" status to confirm whether flows were correctly bypassed based on trigger conditions.

6. Paginate Through High-Volume Runs

If you have high-frequency flows, use this action with page size and page token to programmatically retrieve all flow runs in manageable chunks.

🟦 Inputs

1. Flow ID

**(You can select flow id from the list or add it as a token. from previous steps)**This field identifies the specific Flow whose runs you want to list. You can either:

Select from a list of available Flows in your workspace, or
Use a token from a previous step (e.g., "Read Flow Information" action) to dynamically supply the Flow ID.✅ Example: Using token{{Flow.Id}} to list runs for the current flow.

2. Start Date

**(Please select the start date of runs you wish to get. you can select that using calendar sign)**Defines the earliest run start date to include in the results. Runs that began before this date will be excluded. 📅 Use the calendar picker to simplify selection. ✅ Example: Set to2024-07-01 to retrieve all runs from July onward.

3. End Date

**(Please select the end date of runs you wish to get. you can select that using calendar sign)**Defines the latest run start date to include in the results. Used in combination with the Start Date to define a range. ✅ Example: Set to2024-07-31 to limit results to runs started in July.

4. Status

**(Please select the status of runs you wish to get: 'all', 'executing', 'completed', 'faulted', 'cancelled', 'skipped', 'faulted resume next')**Filters flow runs by their execution status. Options include:

all: No filter, return every run
executing: Runs currently in progress
completed: Successfully finished
faulted: Encountered an error
cancelled: Stopped manually
skipped: Triggered but not executed (trigger condition not met)
faulted resume next: Failed but continued due to error handling✅ Example: Usefaulted to identify flows needing attention.

5. Page Size

**(Maximum number of items to return (must be between 1 and 500))**Limits the number of flow run records returned in a single response. Ideal for paging through a large dataset efficiently. ✅ Example: Use100 to retrieve 100 runs per request.

6. Page Token

**(The token to fetch the next page of data. If not specified, the first page will be returned)**Used for pagination. After a request, you’ll receive a Next Page Token in the output (if more data exists). Pass this token into the next request to get the next batch of results. ✅ Example: Use token from a previous run's output to continue listing.

🟩 Outputs

1. Next Page Token

**(The token to fetch the next page of data. If there is no more records to return, this will be empty.)**This token is returned when there are more flow runs available beyond the current page.

Use this value in the Page Token input to retrieve the next batch of results.
If the value is empty, it means all results have been retrieved.✅ Useful for paginating large sets of flow run data.

2. Instances

This is the list of retrieved flow run records. Each item in this list includes the following fields:

a. Id

**(Id of the run.)**A unique identifier for the specific flow run. ✅ You can use this ID in other Zenphi actions like “Find Flow Run Details.”

b. Name

**(Name of the run.)**The name of the flow run, often based on the Flow’s naming pattern or initial trigger info. ✅ Helps visually identify and reference the run in reports or dashboards.

c. Start Time

**(Exact time of the run execution.)**The precise timestamp when the flow run was initiated. ✅ Useful for calculating duration, trends, or filtering runs by date.

d. Finish Time

**(Exact time of finishing the run execution.)**The exact time the flow run completed its execution — whether successfully or with error. ✅ Helpful for auditing flow performance or troubleshooting.

e. Status

**(The status of the run.)**Current or final execution status of the flow run:

Executing, Completed, Faulted, Skipped(trigger condition not met), Cancelled(manually stopped), etc.✅ Enables filtering or reporting on flow health and behavior.

f. Deleted Flow Execution Data

**(This shows if the flow execution data has been deleted or not.)**Indicates whether detailed execution logs for this run are still available.

true = logs are deleted (the flow run was either manually deleted or is too old and has been removed automatically due to data retention policies.)
false = logs are accessible✅ Important for debugging — ensure logs are retained when needed.

g. Flow ID

**(The ID of the flow related to this flow run.)**The unique identifier of the flow to which this run belongs. ✅ Can be used to group or filter flow runs by a specific flow.

h. Flow Version

**(The flow version related to this flow run.)**Shows which version of the flow was used during the run — especially helpful if the flow has been updated multiple times. ✅ Useful for debugging issues introduced in newer versions.

i. Initiator Email

**(The email address of the person who started this flow, if it applicable.)**Displays the email of the user or system who triggered the flow. ✅ Ideal for auditing, user tracking, or permission control.

j. Trigger Type

**(The type of trigger started this flow run.)**Shows how the flow was initiated, such as:

Form Trigger, On Demand Trigger, HTTP Trigger, etc.✅ Valuable for understanding flow entry points or trigger patterns.

🧪 Example: Monitor Flow Run History for a Specific Process

**Scenario:**Imagine you have a "Leave Request Approval" flow that employees submit through a Zenphi form. As an HR manager, you want to track all flow runs for this process during the past month, to analyze approval durations, failure rates, and who initiated each request.

How to set it up:

Add the "List Flow Runs" action to your flow.
In the Flow ID field, select the "Leave Request Approval" flow.
Use the Start Date and End Date fields to filter runs for the last 30 days.
Set Status to “all” if you want to include every run regardless of outcome.
Optionally, set a Page Size (e.g., 100) to limit results per page.

Once the flow runs are retrieved, you can loop through each instance using a "For Each" action to:

Log failed requests.
Collect run durations.
Notify initiators of any skipped or faulted flows.

✅ This setup helps teams maintain visibility, ensure accountability, and debug process issues efficiently.