> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Task Executions
> Monitor agent task executions, analyze workflow steps, track performance metrics, and debug agent behavior in real-time
Task executions provide complete visibility into how your agents process work. Every triggered task creates an execution record showing the full workflow path, tool outputs, evaluation scores, and decision logic.
## Understanding Task Executions
Every task execution represents a single workflow run from trigger to completion. Beam captures the complete execution trace including:
**Execution Metadata** - Task ID, trigger source, start/end timestamps, overall status
**Workflow Steps** - Every node executed with inputs, outputs, and tool usage
**Branch Decisions** - Which paths were selected and why based on conditions
**Evaluation Metrics** - Accuracy scores and validation results per step
**Performance Data** - Execution duration, token usage, API calls made
## Viewing Task Executions
### Tasks Overview
The Tasks page displays all executions for your agent in chronological order.
**Task List Features:**
* **Task ID**: Unique identifier and custom task number
* **Description**: Auto-generated summary from trigger input or manual entry
* **Status Indicator**: Completed (green), In Progress (blue), Failed (red), Pending (gray)
* **Timestamp**: Execution start time and date
* **Search & Filter**: Find tasks by name, status, or date range
* **Create Task**: Manually trigger new execution
**Status Types:**
Workflow finished successfully through all nodes to exit point
Currently executing - real-time updates as nodes complete
Stopped due to error, timeout, or validation failure
Queued for execution or awaiting human approval (HITL mode)
### Task Execution Details
Click any task to view the complete execution breakdown in the right panel.
**Execution Panel Sections:**
**Task Header** - Shows current step progress (2/6), task name, completion status
**Attachments** - Files uploaded with the task (PDFs, images, documents)
**Task Execution Timeline** - Visual flowchart of all workflow steps
**Output Panel** - Final results, messages, and extracted data
**Input Panel** - Original trigger data or manual input provided
## Analyzing Executions
### Workflow Step Breakdown
Each step in the timeline shows the exact sequence of agent actions.
**Step Information:**
* **Step Name**: Node objective (e.g., "Extract the Required Information from the Invoice")
* **Tool Used**: Integration or Custom GPT tool icon
* **Accuracy Score**: Evaluation percentage (100%, 95%, etc.)
* **Status Icon**: Green checkmark (passed), red X (failed), yellow warning (needs review)
**Step Status Indicators:**
* ✅ **Green Checkmark**: Step completed successfully, passed all evaluations
* ❌ **Red X**: Step failed validation or encountered error
* ⚠️ **Yellow Warning**: Step completed but flagged for review
* 🔄 **Blue Spinner**: Currently executing in real-time
**Step Input** - Shows the exact data the node received:
* Variables from trigger (`task_query`)
* Outputs from previous nodes
* Static configuration values
* Memory file references
**Step Output** - The result generated by the node:
* Extracted data from documents
* API responses from integrations
* Generated text or classifications
* Structured JSON objects
**Example:**
```json theme={null}
{
"extracted_invoiced_details": {
"Buyer Name": "Quantum Technologies",
"Tax Amount": "$384.00",
"Invoice Date": "May 15, 2024",
"Total Amount": "$5,184.00"
}
}
```
Explains how the agent approached the task:
* Which tool was selected and why
* Decision logic and confidence scores
* Alternative approaches considered
* Evaluation criteria applied
Access via "View tool details" link in step panel.
Shows accuracy and quality scores:
* Overall step accuracy percentage
* Individual criterion pass/fail status
* Auto-generated evaluation rules
* Feedback and improvement suggestions
Expandable "Evaluation metrics" section at step bottom.
### Branch Logic & Path Selection
Agents make decisions on which workflow path to follow based on conditions.
**Branch Visualization:**
* **Selected Path**: Highlighted with green checkmark icon
* **Not Selected Path**: Grayed out with red X icon
* **Condition Logic**: Expandable dropdown showing "If the validation is successful" vs "If the validation is unsuccessful"
* **Reasoning**: Why agent chose specific path based on previous step outputs
This transparency allows you to trace exactly why the agent took specific actions.
## Creating & Managing Tasks
### Manual Task Creation
Trigger tasks manually for on-demand processing or testing using the **Create Task** button.
Enter natural language instructions for the agent to process.
**Example:**
```
Extract customer information from the attached contract
and update the CRM system
```
Agent interprets instructions and routes to appropriate workflow nodes.
Attach documents for the agent to process:
* PDFs, Word docs, Excel spreadsheets
* Images (JPEG, PNG for OCR)
* CSV data files
* URLs to parse
Files become available via `task_query.encodedContextFiles`.
Select from recent executions to rerun with same inputs.
**Use Cases:**
* Test workflow changes with known data
* Debug failed executions
* Verify fixes after agent modifications
* Compare results before/after optimization
Provide structured data directly for precise testing.
**Example:**
```json theme={null}
{
"task": "Validate invoice data",
"invoice_number": "INV-2025-001",
"amount": 1500.00,
"vendor": "Acme Corp"
}
```
Matches webhook payload format for integration testing.
### Performance Metrics
Track agent performance across all task executions:
**Completion Rate** - Percentage of tasks finishing successfully
**Average Runtime** - Mean execution duration from start to completion
**Evaluation Scores** - Average accuracy across all steps and tasks
**Success by Trigger** - Completion rates by trigger source (Email, Webhook, Manual, Timer)
Access detailed performance data through the Analytics tab.
**Completion Trends** - Visualize task completion rates over time with daily, weekly, monthly aggregation
**Runtime Analysis** - Identify slowest steps and bottlenecks in execution flow
**Evaluation Insights** - Track quality improvements and failure patterns
**Tool Performance** - See which integrations perform best with success rates and response times
## Debugging & Best Practices
### Debugging Failed Executions
Failed tasks appear with red status indicator in task list.
**Common Failure Causes:**
**Validation Failure** - Step didn't meet evaluation criteria (e.g., accuracy \< 90%)
**Tool Error** - Integration API returned error or timeout
**Missing Data** - Required field not present in trigger input or previous step output
**Timeout** - Execution exceeded maximum duration limit
Scroll through execution timeline to find red X status icon. Failed step shows error message and which criteria wasn't met.
Verify the node received expected data format. Common issues: incorrect variable mapping, null/empty previous step, data type mismatch.
Examine what the tool actually returned vs expected. Integration errors often include API error codes.
Look at which evaluation criteria failed. Adjust criteria thresholds or improve prompts based on failures.
Make changes to workflow, then re-run the same task to verify fix.
Check task executions daily during initial deployment:
* Monitor completion rates
* Review evaluation scores
* Identify recurring failures
* Validate output quality
Gradually reduce frequency as agent stabilizes (95%+ success rate).
Configure notifications for execution failures via email, Slack, or webhook to ticketing system. Respond quickly to prevent backlog buildup.
Establish expected performance benchmarks:
* Target completion rate (e.g., 95%)
* Maximum acceptable runtime (e.g., 2 minutes)
* Minimum evaluation scores (e.g., 90%)
Alert when metrics deviate beyond thresholds.
Use re-run feature to test changes:
* Keep 10-20 representative tasks saved
* Re-run after workflow modifications
* Compare results before/after changes
Maintain test case library for regression testing.
**Cause**: Human-in-the-loop approval required or queue backlog
**Solution**:
* Check Automation Modes settings (HITL enabled?)
* Review pending approvals in Inbox
* Verify agent has sufficient processing capacity
**Cause**: Evaluation criteria too broad or subjective
**Solution**:
* Make criteria more specific and measurable
* Use exact value matching instead of fuzzy matching
* Regenerate criteria based on successful tasks
**Cause**: Real-time connection lost or browser cached state
**Solution**:
* Refresh page to reconnect WebSocket
* Check network connection stability
* Clear browser cache if issue persists
## Next Steps
Configure human-in-the-loop workflows and approval processes
Test workflow changes with previous task data
Set up quality criteria and accuracy scoring
Improve agent performance with AI-assisted optimization