Create a task execution record
Create a new task execution record for a specific task within a flow execution.
Overview Task executions represent individual task invocations within a flow execution. Each task in a flow can be executed multiple times (retries, loops), tracked by task_execution_idx. This endpoint is primarily used by system workers to report task execution state.
Resource Hierarchy Organization → Flow → Flow Execution → Task Execution
Lifecycle Task executions progress through states: queued → running → completed/failed
- queued: Task scheduled but not yet started
- running: Task currently executing
- completed: Task finished successfully with output
- failed: Task encountered an error
Use Cases
- Workers reporting task execution start/completion
- Recording task outputs for downstream tasks
- Tracking task execution history and retries
- Debugging failed workflow executions
Idempotency This endpoint is idempotent based on (flow_execution_id, task_name, task_execution_idx). If a task execution with these identifiers exists, it will be updated rather than creating a duplicate.
Performance Notes WebSocket notifications are processed in the background to ensure fast worker responses. The endpoint returns immediately after database write; notifications are async.
Related Endpoints
- GET /task-executions - List task executions with filtering
- PUT /task-executions - Update existing task execution and optionally re-execute flow
- GET /flow-executions/{id} - View parent flow execution
Header Parameters
Body Parameters
Error information when task execution fails. Only set when status is 'failed'. Contains error message, type, and stack trace. Structure: {'message': str, 'type': str, 'traceback': str} Used for debugging and error reporting.
ID of the parent flow execution containing this task. Used to determine organization_id and maintain execution hierarchy.
Input parameters provided to the task executor. Schema varies by task type. Can be dict, list, or primitive types. NULL if task has no input parameters.
Output data produced by the task executor upon completion. Only set when status is 'completed'. NULL for queued/running/failed states. Available to downstream tasks via {{task_name.output}} syntax.
Current execution status of the task. Valid values: 'queued', 'running', 'completed', 'failed', 'cancelled'. Server validates against ExecutionStatus enum. Status transitions are: queued → running → (completed|failed|cancelled).
Zero-based execution index for this task. Increments for each execution of the same task (retries, loops). Combines with flow_execution_id and task_name to form unique identifier.
Name of the task as defined in the flow definition YAML. Must match a task name in the flow's task list. Case-sensitive identifier used for task lookups.
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
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.