Feat/add status filter to workflow runs

[twjackysu]

Important

1. Make sure you have read our contribution guidelines
2. Ensure there is an associated issue and you have been assigned to it
3. Use the correct syntax to link this PR: Fixes #<issue number>.

Fixes #26849

Summary

This PR adds optional status filtering, time range filtering, and count statistics endpoints to the workflow run console API. This enhancement allows developers to:

1. Filter workflow runs by status - Query workflow runs with an optional status parameter (running, succeeded, failed, stopped, partial-succeeded)
2. Filter by time range - Query workflow runs created within a specific time range (e.g., 7d, 4h, 30m, 30s)
3. Get count statistics - New endpoints to retrieve total counts and breakdown by status, with optional time range filtering
4. Monitor long-running workflows - Identify workflows that are still running after a certain period
5. Improve API usability - Backward compatible changes that make it easier to monitor and analyze workflow execution

Changes Made

API Endpoints Enhanced:

• GET /console/api/apps/{app_id}/workflow-runs - Added optional status query parameter
• GET /console/api/apps/{app_id}/advanced-chat/workflow-runs - Added optional status query parameter
• GET /console/api/apps/{app_id}/workflow-runs/count - New endpoint for count statistics with optional status and time_range filters
• GET /console/api/apps/{app_id}/advanced-chat/workflow-runs/count - New endpoint for advanced chat count statistics with optional status and time_range filters

New Features:

• Time Range Filtering: Filter workflow runs by created_at timestamp using intuitive time duration format
  • Supported formats: 7d (7 days), 4h (4 hours), 30m (30 minutes), 30s (30 seconds)
  • Filters based on created_at field to include all workflow runs regardless of status
  • Can be combined with status filter for powerful queries

Implementation Layers:

• Controller:
  • Added status and time_range parameter parsing
  • Added count endpoint handlers with comprehensive API documentation
  • Custom input validation for time duration format
• Service:
  • Implemented count methods with status and time range filter support
  • Passes filters through to repository layer
• Repository:
  • Added get_workflow_runs_count() method with SQL aggregation using GROUP BY
  • Time filtering implemented at database level using WHERE created_at >= threshold
  • Efficient query construction with proper index usage
• Fields:
  • Added workflow_run_count_fields response field definitions
• Utils:
  • Added libs/time_parser.py for parsing time duration strings
  • Added libs/custom_inputs.py for Flask-RESTX input validation
  • Uses timezone-aware datetime (UTC) to avoid deprecation warnings

API Examples

List with status filter:

GET /console/api/apps/{app_id}/workflow-runs?status=succeeded&limit=20

Get all status counts:

GET /console/api/apps/{app_id}/workflow-runs/count

Response:
{
  "total": 10,
  "running": 2,
  "succeeded": 5,
  "failed": 2,
  "stopped": 1,
  "partial-succeeded": 0
}

Get specific status count:

GET /console/api/apps/{app_id}/workflow-runs/count?status=succeeded

Response:
{
  "total": 5,
  "running": 0,
  "succeeded": 5,
  "failed": 0,
  "stopped": 0,
  "partial-succeeded": 0
}

Get counts for recent workflow runs (last 7 days):

GET /console/api/apps/{app_id}/workflow-runs/count?time_range=7d

Response:
{
  "total": 50,
  "running": 5,
  "succeeded": 35,
  "failed": 8,
  "stopped": 2,
  "partial_succeeded": 0
}

Use Cases

1. Performance Monitoring: Track workflow completion rates over different time periods
2. Alerting: Identify workflows that have been running for too long
3. Troubleshooting: Quickly find recent failures for debugging
4. Dashboard Integration: Power real-time monitoring dashboards with accurate statistics
5. Capacity Planning: Analyze workflow execution patterns over time

Technical Details

Database Query Optimization:

• All filtering happens at the database level (no post-fetch filtering)
• Uses existing indexes on created_at, status, tenant_id, app_id
• Efficient GROUP BY aggregation for count statistics
• No additional database columns or migrations required

Backward Compatibility:

• All new parameters are optional
• Existing API calls continue to work without changes
• No breaking changes to response formats

Code Quality:

• Follows existing code patterns and conventions
• Uses timezone-aware datetime (UTC) per Python 3.12+ best practices
• Comprehensive error handling and input validation
• All code passes ruff linting and `basedpyright

Screenshots

Not applicable - API-only changes with no UI modifications.

Before	After
...	...

Checklist

• This change requires a documentation update, included: Dify Document
• I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.
• I ran dev/reformat(backend) and cd web && npx lint-staged(frontend) to appease the lint gods

The console API is only for self-hosting; there is no existing API documentation.

[gemini-code-assist]

Summary of Changes

Hello @twjackysu, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the monitoring and analysis capabilities for workflow runs by extending the console API. It introduces the ability to filter workflow run lists by status and provides dedicated endpoints to retrieve comprehensive count statistics, offering a clearer overview of workflow execution states.

Highlights

• API Enhancements for Workflow Runs: Existing API endpoints for listing workflow runs (GET /console/api/apps/{app_id}/workflow-runs and GET /console/api/apps/{app_id}/advanced-chat/workflow-runs) now support an optional status query parameter, allowing users to filter runs by their current state (e.g., running, succeeded, failed).
• New Workflow Run Count Endpoints: Two new API endpoints have been introduced: GET /console/api/apps/{app_id}/workflow-runs/count and GET /console/api/apps/{app_id}/advanced-chat/workflow-runs/count. These endpoints provide count statistics for workflow runs, including a total count and a breakdown by status, with an optional status filter to get the count for a specific status.
• Backend Logic for Filtering and Counting: The service and repository layers have been updated to support the new filtering and counting functionalities. This includes modifications to get_paginated_workflow_runs to accept a status filter and the addition of a new get_workflow_runs_count method in the repository, which intelligently handles status-specific counts or aggregated counts across all statuses using SQL GROUP BY.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request effectively adds status filtering and count statistics to the workflow runs API. The changes are well-organized across the controller, service, and repository layers. My review includes suggestions for improving input validation for the new 'status' parameter, enhancing API response consistency, and refactoring some duplicated code in both the service and repository layers for better maintainability. I've also noted a small correction for a docstring to improve clarity. Overall, this is a solid contribution.

[twjackysu]

I forgot to run reformat after applying the Gemini suggestions and adding the UT. Give me some time to fix this issue.

[crazywoola]

Please mark this PR Ready for review once you have finished working on this.

[crazywoola]

Please fix the broken tests.

[twjackysu]

Please fix the broken tests.

failed action

I don't quite understand the connection between the error message and my changes.
It feels like an unstable test case, as it runs fine on my side without any code modification.
Would you be able to rerun the test to see if it succeeds? If it continues to fail, I may need to look into it.

[twjackysu]

Due to the monitor's requirement, I add an optional time_range filter to workflow-runs/count
/gemini review

[gemini-code-assist]

Code Review

This pull request introduces valuable new features for filtering and counting workflow runs by status and time range. The implementation is solid, with new API endpoints, service logic, and repository methods, along with comprehensive unit tests. My review focuses on improving code quality by addressing code duplication, a critical bug in dictionary handling, and enhancing maintainability and correctness. Specifically, I've suggested refactoring duplicated controller logic, using constants for repeated values, fixing a dictionary unpacking error, improving import statements, and parameterizing a hardcoded value in the service layer to ensure correct behavior across different contexts.

[twjackysu]

The workflow seems to be stuck for some unknown reason. Can we cancel it and rerun it?

[crazywoola]

Thanks for the PR :) I have restored the broken CI pipeline