Update task execution and optionally re-execute flow
Update an existing task execution and optionally trigger flow re-execution.
Overview This endpoint updates a task execution's output, status, or other fields, and can automatically propagate changes to downstream tasks by re-executing the flow. Commonly used for human-in-the-loop workflows or manual corrections.
Update Behavior When updating a task execution, the system:
- Updates the task execution record in the database
- Recalculates task output summaries for the parent flow execution
- Identifies downstream tasks that depend on the updated task (stale tasks)
- Optionally re-executes those stale tasks if execute_flow=true
Stale Task Detection Tasks become "stale" when an upstream task they depend on changes. The system analyzes task dependencies from the flow definition to determine affected tasks. Only stale tasks are re-executed, not the entire flow.
Use Cases
- Correcting task outputs after manual review (human-in-the-loop)
- Updating task results based on external feedback
- Fixing data quality issues in completed tasks
- Triggering partial flow re-execution after corrections
Concurrency Updates use optimistic locking via updated_at timestamp. Concurrent updates to the same task execution may result in last-write-wins behavior.
Related Endpoints
- POST /task-executions - Create new task execution
- POST /flow-executions/{id}/execute - Re-execute entire flow
- GET /task-executions - List task executions with filtering
Header Parameters
Query Parameters
Whether to re-execute downstream tasks after updating this task execution. If true, identifies all tasks that depend on this task (stale tasks) and triggers their re-execution with updated inputs. If false, only updates the task execution record without propagation. Default: false for safety (explicit opt-in for re-execution).
Body Parameters
ID of the parent flow execution containing this task. Establishes the execution hierarchy and determines organization scope. All tasks in a flow execution share the same flow_execution_id.
Unique identifier for this task execution. Auto-generated UUID assigned at creation time. Used for direct resource access via GET /task-executions/{id}.
Input parameters provided to the task executor. Schema varies by task type; can be object, array, or primitive. NULL if task accepts no input parameters. Resolved from flow definition and upstream task outputs.
Identifier of the actor who last modified this task execution. Tracks manual interventions vs automated updates for auditing. Defaults to 'system' for worker-initiated changes.
Values:
- 'system': System-automated changes (workers, background jobs)
- User ID: UUID string of the user who made the change (e.g., '123e4567-e89b-12d3-a456-426614174000')
- Integration type: For service accounts/integrations (e.g., 'integration', 'service-account')
ID of the organization owning this task execution. Inherited from parent flow execution for tenant isolation. Used for Row-Level Security (RLS) filtering and authorization. All task executions are scoped to a single organization.
Current execution state of the task. Valid values: 'queued', 'running', 'completed', 'failed', 'deleted', 'stale'.
Status transitions:
- queued → running: Task execution started
- running → completed: Task succeeded with output
- running → failed: Task encountered error
- any → deleted: Task soft-deleted (hidden from list operations)
- completed/failed → stale: Task data is outdated <...
Zero-based execution index tracking task attempts. 0 = first execution, 1 = first retry, 2 = second retry, etc. Increments for each retry or loop iteration of the same task. Combines with flow_execution_id and task_name to form unique composite key.
Name of the task as defined in the flow definition YAML. Case-sensitive identifier matching flow configuration. Used to reference task in flow logic and dependency graphs.
Response
Response Attributes
ID of the parent flow execution containing this task. Establishes the execution hierarchy and determines organization scope. All tasks in a flow execution share the same flow_execution_id.
Unique identifier for this task execution. Auto-generated UUID assigned at creation time. Used for direct resource access via GET /task-executions/{id}.
Input parameters provided to the task executor. Schema varies by task type; can be object, array, or primitive. NULL if task accepts no input parameters. Resolved from flow definition and upstream task outputs.
Identifier of the actor who last modified this task execution. Tracks manual interventions vs automated updates for auditing. Defaults to 'system' for worker-initiated changes.
Values:
- 'system': System-automated changes (workers, background jobs)
- User ID: UUID string of the user who made the change (e.g., '123e4567-e89b-12d3-a456-426614174000')
- Integration type: For service accounts/integrations (e.g., 'integration', 'service-account')
ID of the organization owning this task execution. Inherited from parent flow execution for tenant isolation. Used for Row-Level Security (RLS) filtering and authorization. All task executions are scoped to a single organization.
Current execution state of the task. Valid values: 'queued', 'running', 'completed', 'failed', 'deleted', 'stale'.
Status transitions:
- queued → running: Task execution started
- running → completed: Task succeeded with output
- running → failed: Task encountered error
- any → deleted: Task soft-deleted (hidden from list operations)
- completed/failed → stale: Task data is outdated <...
Zero-based execution index tracking task attempts. 0 = first execution, 1 = first retry, 2 = second retry, etc. Increments for each retry or loop iteration of the same task. Combines with flow_execution_id and task_name to form unique composite key.
Name of the task as defined in the flow definition YAML. Case-sensitive identifier matching flow configuration. Used to reference task in flow logic and dependency graphs.
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.