Skip to main content
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:

​
State Descriptions

StateDescriptionWhat’s Happening
PendingWaiting for a worker to pick up the taskSitting in the task queue, no worker has claimed it yet
RunningActively executing on a workerAgent is performing the work, streaming logs and updates
CompletedSuccessfully finishedTask completed successfully, results are available
FailedExecution encountered an errorSomething went wrong - could retry or needs investigation
CancelledUser or system stopped the executionIntentionally 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: 
# List all executions
kubiya execution list

# List running executions
kubiya execution list --status running

# Get execution details
kubiya execution get <execution-id>

# Stream execution logs
kubiya execution logs <execution-id>

# Cancel an execution
kubiya execution cancel <execution-id>

​
API

Query executions programmatically: 
# List executions with filters
GET /api/v1/executions?status=running&agent_id=<agent-id>

# Get specific execution
GET /api/v1/executions/<execution-id>

# Get execution logs
GET /api/v1/executions/<execution-id>/logs

# Cancel execution
POST /api/v1/executions/<execution-id>/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: 
# Stream logs as execution runs
kubiya execution logs <execution-id> --follow

# Watch execution status updates
kubiya execution watch <execution-id>

​
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 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: 
# 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: 
# View execution details
kubiya execution get <execution-id>

# Check error message and logs
kubiya execution logs <execution-id>

# Review agent configuration
kubiya agent get <agent-id>

# Check policy restrictions
# Review OPA policies that may have blocked actions

​
Long-Running Execution

Problem: Execution taking longer than expected Options: 
# Check if execution is making progress
kubiya execution logs <execution-id> --follow

# If stuck, cancel and retry
kubiya execution cancel <execution-id>

# 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

Task Queues

Understand how task queues distribute work to workers

Workers

Learn about workers that execute tasks

Task Kanban

Manage executions visually on the Kanban board

Background Jobs

Schedule recurring executions with background jobs