> ## 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. # List workflow executions > Retrieve a paginated list of executions for a specific workflow. **Filtering by Bulk ID:** When a `bulk_id` query parameter is provided, the endpoint returns only executions from that specific bulk operation. This allows you to: - Track progress of a batch of executions - Retrieve all executions triggered via the bulk-trigger endpoint - Correlate webhook notifications from the same bulk operation **Usage Example:** ```bash # 1. Trigger a bulk operation POST /workflows/wf-123/bulk-trigger { "inputs": [ {"prompt": "sunset"}, {"prompt": "mountains"}, {"prompt": "ocean"} ] } # Returns: { "bulk_id": "550e8400-e29b-41d4-a716-446655440000", ... } # 2. List all executions from that bulk operation GET /workflows/wf-123/executions?bulk_id=550e8400-e29b-41d4-a716-446655440000 ``` **Note:** When filtering by `bulk_id`, pagination still applies using the same `offset` and `limit` parameters. ## OpenAPI ````yaml /openapi_specs/workflows.json get /workflows/{workflowID}/executions 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: /workflows/{workflowID}/executions: parameters: - $ref: '#/components/parameters/WorkflowID' get: tags: - Executions summary: List workflow executions description: > Retrieve a paginated list of executions for a specific workflow. **Filtering by Bulk ID:** When a `bulk_id` query parameter is provided, the endpoint returns only executions from that specific bulk operation. This allows you to: - Track progress of a batch of executions - Retrieve all executions triggered via the bulk-trigger endpoint - Correlate webhook notifications from the same bulk operation **Usage Example:** ```bash # 1. Trigger a bulk operation POST /workflows/wf-123/bulk-trigger { "inputs": [ {"prompt": "sunset"}, {"prompt": "mountains"}, {"prompt": "ocean"} ] } # Returns: { "bulk_id": "550e8400-e29b-41d4-a716-446655440000", ... } # 2. List all executions from that bulk operation GET /workflows/wf-123/executions?bulk_id=550e8400-e29b-41d4-a716-446655440000 ``` **Note:** When filtering by `bulk_id`, pagination still applies using the same `offset` and `limit` parameters. operationId: listWorkflowExecutions parameters: - name: bulk_id in: query description: > **Optional**: Filter executions by bulk operation ID. When provided, only returns executions from the specified bulk trigger operation. The `bulk_id` is returned when you trigger a workflow via the bulk-trigger endpoint. schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: offset in: query description: > Pagination offset - number of items to skip. The response includes a `offset` field pointing to the next page if more results exist. schema: type: integer format: int32 default: 0 minimum: 0 example: 0 - name: limit in: query description: | Maximum number of executions to return per page. Default: 50 Maximum: 100 schema: type: integer format: int32 default: 50 minimum: 1 maximum: 100 example: 50 responses: '200': description: List of workflow executions content: application/json: schema: $ref: '#/components/schemas/ListExecutionsResponse' examples: normal: summary: Normal workflow execution list value: executions: - execution_id: exec-1 flow_id: wf-123 flow_name: Text to Image Generator version_id: v1 status: completed started_at: '2025-12-20T10:00:00Z' ended_at: '2025-12-20T10:05:00Z' created_at: '2025-12-20T10:00:00Z' updated_at: '2025-12-20T10:05:00Z' - execution_id: exec-2 flow_id: wf-123 flow_name: Text to Image Generator version_id: v1 status: running started_at: '2025-12-20T10:10:00Z' created_at: '2025-12-20T10:10:00Z' updated_at: '2025-12-20T10:10:00Z' offset: 2 total_count: 142 bulk_filtered: summary: Executions filtered by bulk_id value: executions: - execution_id: exec-1 flow_id: wf-123 flow_name: Batch Image Generator version_id: v1 status: completed started_at: '2025-12-20T10:00:00Z' ended_at: '2025-12-20T10:05:00Z' created_at: '2025-12-20T10:00:00Z' updated_at: '2025-12-20T10:05:00Z' - execution_id: exec-2 flow_id: wf-123 flow_name: Batch Image Generator version_id: v1 status: completed started_at: '2025-12-20T10:00:01Z' ended_at: '2025-12-20T10:05:15Z' created_at: '2025-12-20T10:00:01Z' updated_at: '2025-12-20T10:05:15Z' - execution_id: exec-3 flow_id: wf-123 flow_name: Batch Image Generator version_id: v1 status: completed started_at: '2025-12-20T10:00:02Z' ended_at: '2025-12-20T10:04:58Z' created_at: '2025-12-20T10:00:02Z' updated_at: '2025-12-20T10:04:58Z' total_count: 3 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: parameters: WorkflowID: name: workflowID in: path required: true description: Unique workflow identifier schema: type: string example: wf_abc123 schemas: ListExecutionsResponse: type: object description: Paginated list of workflow executions required: - executions - total_count properties: executions: type: array description: Array of execution summaries items: $ref: '#/components/schemas/ExecutionSummary' offset: type: integer format: int32 description: | Offset for the next page of results. If null, there are no more results to fetch. example: 50 total_count: type: integer format: int32 description: Total number of executions matching the query example: 142 example: executions: - execution_id: exec-1 flow_id: wf-123 flow_name: Text to Image Generator version_id: v1 status: completed started_at: '2025-12-20T10:00:00Z' ended_at: '2025-12-20T10:05:00Z' created_at: '2025-12-20T10:00:00Z' updated_at: '2025-12-20T10:05:00Z' - execution_id: exec-2 flow_id: wf-123 flow_name: Text to Image Generator version_id: v1 status: running started_at: '2025-12-20T10:10:00Z' created_at: '2025-12-20T10:10:00Z' updated_at: '2025-12-20T10:10:00Z' offset: 2 total_count: 142 ExecutionSummary: type: object description: | Summary information about a workflow execution, used in list responses. Contains less detail than `ExecutionDetails` to optimize list queries. required: - execution_id - flow_id - flow_name - version_id - status - created_at properties: execution_id: type: string description: Unique execution identifier example: exec-1 flow_id: type: string description: Workflow identifier (UUID) example: wf-123 flow_name: type: string description: Human-readable workflow name example: Text to Image Generator version_id: type: string description: Version identifier for this execution example: v1 api_key: type: string description: User/API key identifier that triggered this execution example: user-456 status: type: string enum: - running - completed - failed - cancelled description: Current execution status example: completed started_at: type: string format: date-time description: >- RFC3339 timestamp when the execution started (omitted if not started yet) example: '2025-12-20T10:00:00Z' ended_at: type: string format: date-time description: >- RFC3339 timestamp when the execution completed (omitted for running executions) example: '2025-12-20T10:05:00Z' created_at: type: string format: date-time description: RFC3339 timestamp when the execution was created example: '2025-12-20T10:00:00Z' updated_at: type: string format: date-time description: RFC3339 timestamp when the execution was last updated example: '2025-12-20T10:05:00Z' deleted_at: type: string format: date-time description: >- RFC3339 timestamp when the execution was soft-deleted (if applicable) example: null inputs: type: object description: Input parameters provided when triggering the workflow additionalProperties: true example: prompt: Generate an image of a sunset step_results: description: > Brief summary of step execution results. Structure varies - may be an object with step IDs as keys, or an array. oneOf: - type: object - type: array items: {} output: type: string description: | Simple string output from the workflow (if available). For complex outputs, use `output_json` instead. example: https://storage.googleapis.com/uploads/image.png output_json: type: object description: | Structured JSON output from the workflow (if available). Contains the full workflow output when output mapping is configured. additionalProperties: true example: image_url: https://storage.googleapis.com/uploads/image.png generation_time: 2.45 cost: description: | Cost information for this execution (if available). Structure varies by provider and workflow configuration. oneOf: - type: object - type: number Error: type: object required: - error properties: error: type: string description: Error message responses: BadRequest: description: Bad request - Invalid input content: application/json: schema: $ref: '#/components/schemas/Error' 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 ````