> ## Documentation Index > Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt > Use this file to discover all available pages before exploring further. # Executions > Durable task instances that represent the runtime execution of agent workflows and tasks. Track progress, monitor status, and manage running work. Executions are the runtime instances of your tasks and workflows. When you ask an agent to perform work, or when a scheduled job runs, an execution is created. Executions are durable, meaning they survive restarts and provide complete history and observability into what happened. ## What is an Execution? An execution is a specific instance of a task or workflow that: * **Has a unique ID** - Every execution gets a globally unique identifier * **Tracks state** - Moves through lifecycle stages: pending → running → completed (or failed) * **Provides observability** - Streams logs, events, and progress in real-time * **Is durable** - Backed by Temporal, executions survive system restarts and failures * **Maintains history** - Complete audit trail of what happened, when, and why Think of an execution like a delivery order: the task is the order form (what needs to be done), while the execution is the actual delivery attempt with tracking updates, current location, and final outcome. ## Execution Lifecycle Executions move through well-defined states: ```mermaid theme={null} stateDiagram-v2 [*] --> Pending: Task Created Pending --> Running: Worker Picks Up Task Running --> Completed: Success Running --> Failed: Error Occurred Running --> Cancelled: User Cancelled Failed --> Running: Automatic Retry Completed --> [*] Failed --> [*] Cancelled --> [*] ``` ### State Descriptions | State | Description | What's Happening | | ------------- | ---------------------------------------- | --------------------------------------------------------- | | **Pending** | Waiting for a worker to pick up the task | Sitting in the task queue, no worker has claimed it yet | | **Running** | Actively executing on a worker | Agent is performing the work, streaming logs and updates | | **Completed** | Successfully finished | Task completed successfully, results are available | | **Failed** | Execution encountered an error | Something went wrong - could retry or needs investigation | | **Cancelled** | User or system stopped the execution | Intentionally stopped before completion | ## Where Executions Appear ### Task Kanban Board The Task Kanban board is the primary interface for managing executions. Each card on the board represents an execution: * **Planning** column: Tasks being planned (not yet executions) * **Pending** column: Executions waiting for workers * **Running** column: Active executions with live progress * **Completed** column: Finished executions with results * **Failed** column: Executions that encountered errors ### CLI List and manage executions from the command line: ```bash theme={null} # List all executions kubiya execution list # List running executions kubiya execution list --status running # Get execution details kubiya execution get # Stream execution logs kubiya execution logs # Cancel an execution kubiya execution cancel ``` ### API Query executions programmatically: ```bash theme={null} # List executions with filters GET /api/v1/executions?status=running&agent_id= # Get specific execution GET /api/v1/executions/ # Get execution logs GET /api/v1/executions//logs # Cancel execution POST /api/v1/executions//cancel ``` ## Execution Metadata Each execution captures rich metadata: ### Identification * **Execution ID**: Unique identifier (UUID format) * **Task ID**: The task definition this execution is running * **Parent Execution**: If this execution was spawned by another (workflows) ### Context * **Agent/Team**: Which agent or team is performing the work * **Environment**: Which environment the execution is running in * **Task Queue**: Which queue the execution was pulled from * **Worker**: Which specific worker is handling the execution ### Timing * **Created At**: When the task was submitted * **Started At**: When a worker picked it up * **Completed At**: When it finished (success or failure) * **Duration**: Total execution time ### Results * **Status**: Current state (pending, running, completed, failed, cancelled) * **Output**: Results returned by the agent * **Error**: Error message if failed * **Logs**: Complete execution logs and events ## Durability and Reliability Executions leverage Temporal's durability guarantees: ### Automatic Retries If an execution fails due to transient errors (network issues, temporary service unavailability), it automatically retries with exponential backoff: * **First retry**: After a few seconds * **Subsequent retries**: Increasing delays between attempts * **Max retries**: Configurable limit before marking as failed ### Crash Recovery If a worker crashes mid-execution: 1. The execution remains in "running" state in Temporal 2. Another healthy worker picks up the execution 3. The execution continues from the last recorded state 4. No work is lost ### Long-Running Executions Executions can run for hours or days: * State is persisted continuously * Progress is tracked through checkpoints * Logs stream in real-time regardless of duration ## Monitoring Executions ### Real-Time Streaming Watch execution progress live: ```bash theme={null} # Stream logs as execution runs kubiya execution logs --follow # Watch execution status updates kubiya execution watch ``` ### Execution Events Executions emit events for key milestones: * Task submitted * Execution started * Agent question (requires user input) * Checkpoint reached * Output generated * Execution completed * Execution failed ### Metrics and Analytics Track execution patterns: * **Throughput**: Executions per hour/day * **Success rate**: Percentage of completed vs failed * **Duration**: Average, min, max execution time * **Queue wait time**: How long tasks wait before starting * **Worker utilization**: How busy your workers are Access these in the [Analytics](/core-concepts/analytics/analytics) dashboard. ## Common Patterns ### Sequential Execution One task triggers another in sequence: ``` Task A → Execution A (completes) → Task B → Execution B ``` ### Parallel Execution Multiple tasks run simultaneously: ``` Task A → Execution A ↘ Task B → Execution B → All complete together Task C → Execution C ↗ ``` ### Conditional Execution Task execution depends on previous results: ``` Task A → Execution A → Check result → If success: Task B, If failure: Task C ``` ### Scheduled Execution Background jobs create executions on a schedule: ``` Cron: "0 2 * * *" → Daily at 2 AM → New Execution → Backup database ``` ## Troubleshooting Executions ### Execution Stuck in Pending **Problem**: Task never starts running **Common causes:** * No workers connected to the task queue * Workers at max capacity * Task queue misconfigured **Solutions:** ```bash theme={null} # Check worker status kubiya worker list # Check queue capacity # View in dashboard: Task Queues → See active workers # Verify task routing # Check environment has workers attached ``` ### Execution Failed **Problem**: Execution completed with error **Investigation steps:** ```bash theme={null} # View execution details kubiya execution get # Check error message and logs kubiya execution logs # Review agent configuration kubiya agent get # Check policy restrictions # Review OPA policies that may have blocked actions ``` ### Long-Running Execution **Problem**: Execution taking longer than expected **Options:** ```bash theme={null} # Check if execution is making progress kubiya execution logs --follow # If stuck, cancel and retry kubiya execution cancel # Review timeout settings # Check if agent needs more time or task needs simplification ``` ## Best Practices ### Execution Management * **Monitor actively**: Watch running executions for errors * **Cancel promptly**: Stop executions that are no longer needed * **Review failures**: Learn from failed executions to improve reliability * **Track metrics**: Monitor success rate and duration trends ### Performance Optimization * **Right-size workers**: Ensure enough worker capacity for your workload * **Tune concurrency**: Adjust max concurrent executions per worker * **Optimize tasks**: Break large tasks into smaller, manageable pieces * **Use priorities**: Route urgent tasks to dedicated high-priority queues ### Observability * **Enable logging**: Ensure agents stream detailed logs * **Set up alerts**: Get notified of execution failures * **Track trends**: Monitor execution patterns over time * **Audit regularly**: Review execution history for security and compliance ## Next Steps Understand how task queues distribute work to workers Learn about workers that execute tasks Manage executions visually on the Kanban board Schedule recurring executions with background jobs