Workflow Execution Filtering and Monitoring
When working with Workflow Deployments in production, you’ll often need to filter and retrieve execution data for monitoring, debugging, or analytics purposes. This guide shows you how to use the Workflow execution API endpoints effectively, including how to construct complex filters programmatically.
Overview
Vellum provides two key endpoints for working with Workflow execution data:
- List Workflow Deployment Executions - Retrieve and filter executions with advanced query capabilities
- Retrieve Workflow Deployment Execution - Get detailed information about a specific execution, including actuals submissions
Advanced Filtering
Understanding Filter Structure
The filters
parameter accepts a JSON string that defines complex filtering conditions. Here’s the basic structure:
Common Filtering Examples
Filter by Timestamp Range
Filter by Execution Status
Complex Multi-Condition Filters
Ordering Results
Use the ordering
parameter to sort execution results. Common ordering options include:
timestamp
- Sort by execution timestamp (oldest first)-timestamp
- Sort by execution timestamp (newest first)state
- Sort by execution state-state
- Sort by execution state (reverse order)
Retrieving Execution Details and Actuals
Once you have an execution ID, you can retrieve detailed information including submitted actuals:
UI Filter Builder Reference
While we recommend using the programmatic approach above, you can also use the Vellum UI to build filters visually and then copy the generated filter structure:

The URL will contain the encoded filter structure that you can decode and use in your API calls:
Common Filtering Fields
Here are the most commonly used fields for filtering Workflow executions:
Supported Operators
When building filter conditions, you can use these operators:
Production Monitoring Patterns
Real-time Error Monitoring
Performance Analytics
Next Steps
- Explore the List Workflow Deployment Executions API reference for complete parameter details
- Learn about Retrieve Workflow Deployment Execution Event API for detailed execution information
- Set up monitoring and webhooks for real-time execution notifications
- Implement Workflow execution actuals to track quality metrics