Create task output
Create a task output record for a completed task and notify connected clients.
Task outputs represent the processed, summarized results of task executions. Unlike task executions which track the full execution lifecycle (input, output, error, status), task outputs focus on the final output data formatted for display, downstream consumption, and workflow decisions.
What Are Task Outputs
Task outputs serve multiple purposes:
- Structured Results: Store task results in a queryable format via the summary field
- Full Output Data: Provide complete output for downstream task consumption
- Metadata Tracking: Associate tags for categorization and filtering
- Real-time Updates: Enable WebSocket notifications for UI progress tracking
- Workflow Logic: Support decision-making based on task outcomes
Relationship to Task Executions
- Task Execution: Full execution record (input, output, error, retries, timing)
- Task Output: Summarized result optimized for querying and display
- One task execution typically produces one task output upon completion
- Task outputs are created by system workers after task completion
Notification Behavior
This endpoint triggers two types of WebSocket notifications asynchronously:
- Flow-level notification: Updates all clients subscribed to the flow's WebSocket
- Enhanced notification: Broadcasts to summary-watching clients for real-time updates
Notifications are processed in the background to ensure fast response times (< 100ms).
Common Use Cases
- Workers reporting task completion with structured output
- Storing task results for display in execution history UI
- Providing data for downstream task inputs in workflows
- Triggering real-time progress updates
- Enabling workflow decisions based on task outcomes
Related Endpoints
GET /task-outputs- List all task outputsGET /task-outputs/{id}- Get single task outputGET /flow-executions/{id}- View parent flow executionGET /task-executions- View full task execution details
Header Parameters
Body Parameters
Valid status values for flow execution lifecycle.
Status Transitions: queued → running → in_progress → completed → failed
Any status → deleted (soft delete)
completed/failed → stale (data outdated)
Status Definitions: - queued: Execution created but workflow not yet started - running: Workflow started, initial tasks executing - in_progress: Workflow actively processing tasks - completed: Al...
queuedrunningin_progresscompletedfaileddeletedstaleResponse
Response Attributes
ID of the parent flow execution containing this task. Establishes the execution hierarchy and organization scope.
Unique identifier for this task output. Auto-generated UUID assigned at creation time. Used for direct resource access via GET /task-outputs/{id}.
Identifier of the actor who last modified this task output. Tracks who made the last change for auditing purposes. 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 output. Inherited from parent flow execution. Used for Row-Level Security (RLS) and multi-tenant isolation.
Execution status when output was created. Valid values: 'queued', 'running', 'completed', 'failed', 'deleted', 'stale'. Typically 'completed' for successful task outputs.
Status meanings:
- queued: Task scheduled but not started
- running: Task actively executing
- completed: Task finished successfully
- failed: Task encountered error (may have partial output)
- deleted: Soft-deleted, excluded from queries (preserves audit trail)
- stale: Output data is outdated (needs refresh)
Structured summary of task output for UI display and querying. Typically a dictionary with standardized keys for rendering.
Common patterns:
- Document processing: {'pages': 10, 'word_count': 5000}
- API calls: {'status_code': 200, 'response_time_ms': 450}
- Data validation: {'valid_rows': 950, 'invalid_rows': 50}
Name of the task that produced this output. Case-sensitive identifier matching flow definition YAML. Used to associate output with specific workflow task.
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
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.