> ## Documentation Index > Fetch the complete documentation index at: https://docs.eachlabs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get execution details > Get the current status and output of a workflow execution ## OpenAPI ````yaml /openapi_specs/workflows.json get /executions/{executionID} openapi: 3.0.3 info: title: Workflows Engine API description: > # Workflows Engine API Execute and monitor AI workflows with a simple, consistent API. ## Quick Start 1. **Trigger a workflow** - POST to `/{workflowID}/trigger` with your inputs 2. **Monitor execution** - GET `/executions/{executionID}` to check status 3. **Optional**: Provide a `webhook_url` to receive automatic notifications when complete --- ## Webhook Notifications When you provide a `webhook_url` when triggering a workflow, the Workflows Engine will automatically **POST** to your endpoint with the execution results when the workflow completes (successfully or with an error). ### Key Features - ✅ **Consistent Payload**: The webhook payload has the same structure as the response from `GET /executions/{executionID}` - ✅ **Automatic Retries**: Failed webhook deliveries are automatically retried with exponential backoff - ✅ **Simple Integration**: No authentication required - your endpoint just needs to accept POST requests ### Webhook Request The engine will POST to your `webhook_url` with: - **Method**: `POST` - **Content-Type**: `application/json` - **Body**: Execution details (see payload structure below) ### Example Webhook Payload ```json { "execution_id": "69ae8c7b-7500-4a45-b7c0-348b8cc2665b", "workflow_id": "50741f40-8621-4d46-8a91-dff4d873be98", "status": "completed", "started_at": "2025-12-04T11:48:10Z", "inputs": { "story": "tell an epic story of a rat graduating from law" }, "step_outputs": { "step1": { "step_id": "step1", "status": "completed", "output": "Once upon a time in Ratropolis...", "primary": "Once upon a time in Ratropolis...", "metadata": { "model": "openai-chatgpt-5", "version": "0.0.1", "params": { "system_prompt": "You are a helpful assistant", "max_output_tokens": 512 } } }, "step2": { "step_id": "step2", "status": "completed", "output": [ "https://storage.googleapis.com/uploads/image1.png", "https://storage.googleapis.com/uploads/image2.png" ], "primary": "https://storage.googleapis.com/uploads/image1.png", "metadata": { "model": "nano-banana-pro", "params": { "num_images": 2, "aspect_ratio": "16:9" } } } }, "output": [ "https://storage.googleapis.com/uploads/image1.png", "https://storage.googleapis.com/uploads/image2.png" ] } ``` ### Example Webhook Handler ```python @app.post("/webhooks/workflow-completed") async def handle_workflow_webhook(request: Request): execution = await request.json() if execution["status"] == "completed": # Process successful execution final_output = execution["output"] step_details = execution["step_outputs"] print(f"Workflow completed: {final_output}") elif execution["status"] == "failed": # Handle failure error = execution.get("error_cause", "Unknown error") print(f"Workflow failed: {error}") return {"received": True} ``` Your webhook endpoint should return a `200 OK` status to acknowledge receipt. --- ## Fallback Configuration Model steps support an optional **fallback configuration** that automatically retries with an alternative model if the primary model invocation fails. This provides resilience against temporary model outages or rate limits. ### How Fallback Works When a model step has fallback configured, the workflow engine will: 1. **Execute the primary model** with its configured parameters 2. **If the primary attempt fails**, automatically execute the fallback model configuration 3. **Mark the step as failed only if both primary and fallback attempts fail** ### Fallback Configuration Add a `fallback` object to any model step in your workflow definition: ```json { "step_id": "generate_image", "type": "model", "model": "flux-dev", "params": { "prompt": "{{inputs.prompt}}", "num_images": 1 }, "fallback": { "enabled": true, "model": "flux-1-1-pro", "params": { "prompt": "{{inputs.prompt}}", "guidance_scale": 7.5 } } } ``` ### Fallback Properties | Property | Type | Description | |----------|------|-------------| | `enabled` | boolean | Enable or disable fallback for this step (default: `true`) | | `model` | string | Alternative AI model identifier to use on failure | | `version` | string | Fallback model version (defaults to primary version when omitted) | | `params` | object | Model-specific parameters for the fallback (supports template variables) | ### Detecting Fallback Usage When a fallback is used, the step's metadata in execution results will include: - `fallback_used: true` - Indicates the step completed using the fallback configuration - `primary_error` - Human-readable description of why the primary attempt failed ### Example Execution Response with Fallback ```json { "step_id": "generate_image", "status": "completed", "output": "https://storage.googleapis.com/uploads/image.png", "metadata": { "model": "flux-1-1-pro", "fallback_used": true, "primary_error": "Primary model flux-dev failed: rate limit exceeded" } } ``` --- ## Unlisted Workflows Versions can be "unlisted" - accessible via direct link but hidden from public listings. **Visibility states:** - **Private** (default): Organization only - **Unlisted**: Accessible via link, hidden from public listings - **Public**: Visible in listings and accessible to everyone **Setting unlisted:** Use `allowed_to_share: true` when creating or updating a version. ```bash # Create unlisted version PUT /workflows/{workflowID}/versions/v1 { "allowed_to_share": true, ... } ``` **Behavior:** - `allowed_to_share: true` → Creates/updates as unlisted - `allowed_to_share: false` → Creates/updates as private - No effect on public versions (never downgraded) version: 1.0.0 x-logo: url: ./logo-white.svg altText: Eachlabs Logo servers: - url: https://workflows.eachlabs.run/api/v1 description: >- Deprecated compatibility production host. This public URL remains supported for now, but will soon move under the api-service host at https://api.eachlabs.ai. security: - ApiKeyAuth: [] tags: - name: Categories description: Workflow categories for organization - name: Workflows description: Workflow and version management - name: Executions description: Workflow execution and monitoring - name: Public Workflows description: Access public and unlisted workflows by organization nickname paths: /executions/{executionID}: parameters: - $ref: '#/components/parameters/ExecutionID' get: tags: - Executions summary: Get execution details description: Get the current status and output of a workflow execution operationId: getExecution responses: '200': description: Execution details content: application/json: schema: $ref: '#/components/schemas/ExecutionDetails' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: ExecutionID: name: executionID in: path required: true description: Execution identifier schema: type: string example: exec_xyz789 schemas: ExecutionDetails: type: object description: > Execution details returned by both `GET /executions/{id}` and webhook notifications. ### Webhook Notifications When you provide a `webhook_url` when triggering a workflow, this same structure will be POSTed to your webhook URL when the execution completes. required: - execution_id - workflow_id - status properties: execution_id: type: string description: Unique execution identifier (UUID format) example: 69ae8c7b-7500-4a45-b7c0-348b8cc2665b workflow_id: type: string description: Workflow identifier (UUID format) example: 50741f40-8621-4d46-8a91-dff4d873be98 bulk_id: type: string format: uuid description: > Bulk operation identifier (only present for executions triggered via bulk-trigger endpoint). All executions from the same bulk operation share this ID, allowing you to: - Query all executions from a bulk operation together - Track batch progress - Correlate webhook notifications from related executions example: 550e8400-e29b-41d4-a716-446655440000 status: type: string enum: - running - completed - failed - cancelled description: | Current execution status: - `running` - Workflow is currently executing - `completed` - Workflow finished successfully - `failed` - Workflow encountered an error - `cancelled` - Workflow was cancelled by user example: completed started_at: type: string format: date-time description: RFC3339 timestamp when the execution started example: '2025-12-04T11:48:10Z' completed_at: type: string format: date-time description: >- RFC3339 timestamp when the execution completed (omitted for running executions) example: '2025-12-04T11:50:53Z' inputs: type: object description: Input parameters provided when triggering the workflow additionalProperties: true example: story: tell an epic story of a rat graduating from law step_outputs: type: object description: > Complete outputs from all workflow steps. Each key is a step ID (e.g., "step1", "step2"), and the value is a `StepOutput` object containing detailed information about that step's execution. additionalProperties: $ref: '#/components/schemas/StepOutput' example: step1: step_id: step1 status: completed started_at: '2025-12-04T11:48:10Z' completed_at: '2025-12-04T11:48:39Z' output: Once upon a time... primary: Once upon a time... metadata: model: openai-chatgpt-5 version: 0.0.1 params: system_prompt: You are a helpful assistant user_prompt: tell an epic story of a rat graduating from law max_output_tokens: 512 step2: step_id: step2 status: completed started_at: '2025-12-04T11:48:39Z' completed_at: '2025-12-04T11:50:53Z' output: - https://storage.googleapis.com/uploads/image1.png - https://storage.googleapis.com/uploads/image2.png primary: https://storage.googleapis.com/uploads/image1.png metadata: model: nano-banana-pro version: 0.0.1 params: prompt: Generate images based on the story num_images: 2 aspect_ratio: '16:9' resolution: 1K output_format: png output: description: > Output from the last completed step in the workflow. This provides quick access to the final result without navigating step_outputs. **Important**: This field is only populated when the workflow status is `completed`. - For `running` workflows: null (even if some steps have completed) - For `failed` workflows: null - For `cancelled` workflows: null - For `completed` workflows: contains output from the chronologically last step The last step is determined by the latest `completed_at` timestamp. The value is extracted from the step's `output` field, or `primary` field as fallback. The type varies based on the workflow's final step: - Text generation steps return a string - Image generation steps return an array of URLs - Structured data steps return an object nullable: true oneOf: - type: string - type: array items: {} - type: object example: - https://storage.googleapis.com/uploads/image1.png - https://storage.googleapis.com/uploads/image2.png error: type: string description: High-level error message (only present if status is "failed") example: ExecutionFailed error_cause: type: string description: >- Detailed error cause with context (only present if status is "failed") example: 'Step ''generate_image'' failed: Model timeout after 30s' StepOutput: type: object description: | Detailed information about a single step's execution within a workflow. Each step in the workflow produces one of these objects. required: - step_id - status properties: step_id: type: string description: Unique identifier for this step within the workflow example: step1 status: type: string enum: - queued - running - completed - failed - cancelled description: > Current status of this step: - `queued` - Step is waiting to execute - `running` - Step is currently executing - `completed` - Step finished successfully - `failed` - Step encountered an error - `cancelled` - Step was skipped due to an earlier failure in the workflow example: completed started_at: type: string format: date-time description: >- RFC3339 timestamp when the step started executing (omitted for queued steps) example: '2025-12-04T11:48:10Z' completed_at: type: string format: date-time description: >- RFC3339 timestamp when the step finished (only present if completed or failed) example: '2025-12-04T11:48:39Z' output: description: | The step's output data. The structure depends on the step type: - Text generation: string - Image generation: array of URLs - Structured data: object - Multi-output steps: array or object with multiple values oneOf: - type: string - type: array items: {} - type: object - type: number - type: boolean example: Once upon a time in the city of Ratropolis... primary: description: > The primary output value from this step. For steps that return multiple values (e.g., generating multiple images), this field contains the first/main result for quick access. oneOf: - type: string - type: number - type: boolean - type: object example: https://storage.googleapis.com/uploads/image1.png input: type: object description: > The complete resolved input payload sent to this step handler. This includes the full step configuration with all template values resolved: - `step_id` - The step identifier - `type` or `model` - The step type or model name - `version` - API version (if applicable) - `params` or `inputs` - All parameters with values from previous steps resolved Values like `{{step1.output}}` are replaced with actual data from prior steps. additionalProperties: true example: step_id: generate_image model: flux-dev version: 1.0.0 params: prompt: Generate an image of a rat graduating from law school num_images: 2 metadata: type: object description: > Step configuration and runtime information. Fields vary by step type: **Model steps** include: - `model` - The AI model identifier (e.g., "openai-chatgpt-5") - `version` - API version for the step handler (e.g., "0.0.1") - `params` - All parameters sent to the model - `prediction_id` - External prediction ID (when completed) - `processed_at` - Processing timestamp (when completed) - `fallback_used` - Present and `true` when the primary attempt failed and the fallback configuration was used - `primary_error` - Human-readable error message from the primary attempt when fallback was used **HTTP steps** include: - `type` - Always "http" - `method` - HTTP method (e.g., "GET", "POST") - `url` - Request URL - `params` - Request parameters - `elapsed_seconds` - Request duration (when completed) **Python steps** include: - `type` - Always "python" - `params` - Input parameters - `execution_time` - Execution duration in seconds (when completed) - `processed_at` - Processing timestamp (when completed) properties: model: type: string description: The AI model used (model steps only) example: openai-chatgpt-5 version: type: string description: API version (model steps only) example: 0.0.1 type: type: string description: Step type (http or python steps) enum: - http - python example: http method: type: string description: HTTP method (http steps only) example: POST url: type: string description: Request URL (http steps only) example: https://api.example.com/endpoint params: type: object description: Complete parameters sent to the step, including resolved values additionalProperties: true example: system_prompt: You are a helpful assistant user_prompt: tell an epic story of a rat graduating from law max_output_tokens: 512 prediction_id: type: string description: External prediction ID (model steps, when completed) example: 6yxkzw4th9rme0ct1re8q42xer processed_at: type: string format: date-time description: Processing timestamp (when available) example: '2025-12-04T11:48:39Z' fallback_used: type: boolean description: > Indicates that the step completed successfully using a configured fallback after the primary attempt failed (model steps only). example: true primary_error: type: string description: > Original error message from the primary attempt when a fallback configuration was used (model steps only). example: primary model failed due to timeout elapsed_seconds: type: number description: Execution duration in seconds (when completed) example: 2.45 execution_time: type: number description: Python execution time in seconds (python steps, when completed) example: 0.123 error: type: string description: Error message if the step failed example: ModelTimeout error_cause: type: string description: Detailed error information if the step failed example: Model request timed out after 30 seconds Error: type: object required: - error properties: error: type: string description: Error message responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Not found - Resource does not exist content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key for authentication ````