Executions - Kubiya

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

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:

# 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:

The execution remains in “running” state in Temporal
Another healthy worker picks up the execution
The execution continues from the last recorded state
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

​What is an Execution?

​Execution Lifecycle

​State Descriptions

​Where Executions Appear

​Task Kanban Board

​CLI

​API

​Execution Metadata

​Identification

​Context

​Timing

​Results

​Durability and Reliability

​Automatic Retries

​Crash Recovery

​Long-Running Executions

​Monitoring Executions

​Real-Time Streaming

​Execution Events

​Metrics and Analytics

​Common Patterns

​Sequential Execution

​Parallel Execution

​Conditional Execution

​Scheduled Execution

​Troubleshooting Executions

​Execution Stuck in Pending

​Execution Failed

​Long-Running Execution

​Best Practices

​Execution Management

​Performance Optimization

​Observability

​Next Steps