beam-ai-team/beam-get-task-details

Beam Get Task Details

Retrieve detailed information about a specific Beam.ai task.

Safety Contract

This skill is read-only for Beam state. Before saving or sharing task details, show the workspace, task IDs, destination path, and whether full parameters, node outputs, or customer-sensitive fields are included. Require explicit user approval in the current turn before exporting details outside the local workspace. Do not retry, approve, reject, resume, or update tasks from this skill.

When to Use

• Check the current status of a task
• View task parameters and input data
• Inspect node execution details
• Debug task issues (parameter extraction, graph state)
• Get task metadata (timestamps, custom IDs)

---

Prerequisites

.env file at project root:

# Beam.ai - BID instance (default)
BEAM_API_KEY=<bid-api-key>
BEAM_WORKSPACE_ID=<bid-workspace-id>

# Beam.ai - Production instance
BEAM_API_KEY_PROD=<prod-api-key>
BEAM_WORKSPACE_ID_PROD=<prod-workspace-id>

Dependencies: pip install requests python-dotenv

---

Quick Start

# Get task details
python 03-skills/beam-get-task-details/scripts/get_task_details.py <task_id>

# Get task details from production
python 03-skills/beam-get-task-details/scripts/get_task_details.py <task_id> --workspace prod

# Output as JSON
python 03-skills/beam-get-task-details/scripts/get_task_details.py <task_id> --json

# Get multiple tasks
python 03-skills/beam-get-task-details/scripts/get_task_details.py <task_id1> <task_id2> <task_id3>

# Save output to file
python 03-skills/beam-get-task-details/scripts/get_task_details.py <task_id> --output task_details.json

---

Workspaces

| Workspace | API Endpoint | Default | |-----------|--------------|---------| | bid | api.bid.beamstudio.ai | Yes | | prod | api.beamstudio.ai | No |

---

CLI Reference

| Flag | Description | Default | |------|-------------|---------| | task_ids | One or more task IDs (required) | - | | --workspace, -w | Workspace: bid or prod | bid | | --json | Output as JSON | false | | --full | Show full response (all fields) | false | | --output, -o | Save to file | - |

---

Response Fields

Core Fields

| Field | Description | |-------|-------------| | id | Task ID (UUID) | | customId | Custom identifier (if provided) | | status | Task status (COMPLETED, FAILED, IN_PROGRESS, etc.) | | createdAt | Task creation timestamp | | updatedAt | Last update timestamp | | completedAt | Completion timestamp (if completed) |

Task Statuses

| Status | Description | |--------|-------------| | QUEUED | Task is queued for execution | | IN_PROGRESS | Task is currently running | | COMPLETED | Task completed successfully | | FAILED | Task failed during execution | | ERROR | Task encountered an error | | STOPPED | Task was stopped (condition failed) | | TIMEOUT | Task timed out | | USER_INPUT_REQUIRED | Task waiting for user input | | CANCELLED | Task was cancelled |

Node Execution Details

| Field | Description | |-------|-------------| | agentTaskNodes | Array of node execution data | | agentTaskNodes[].toolData | Node tool configuration and reasoning | | agentTaskNodes[].userQuestions | Required user inputs |

Graph State

| Field | Description | |-------|-------------| | graphState.current | Current node in execution | | graphState.variables | Task variables and context |

---

Example Output

Task Details
============================================================

Task ID:     abc123-def456-789...
Custom ID:   INS-12345
Status:      COMPLETED
Created:     2024-01-15T10:30:00Z
Updated:     2024-01-15T10:31:45Z
Completed:   2024-01-15T10:31:45Z

=== EXECUTION ===
Duration:    105 seconds
Nodes:       5 executed

=== NODE DETAILS ===
[1] ParameterExtraction
    Status: completed
    Parameters extracted: company_name, contact_email

[2] DataLookup
    Status: completed
    Tool: hubspot_search

[3] ProcessData
    Status: completed

[4] GenerateOutput
    Status: completed

[5] SendNotification
    Status: completed

=== RESULT ===
{
  "success": true,
  "output": "Task completed successfully"
}

---

API Details

Uses Beam.ai task details endpoint:

• Endpoint: GET /agent-tasks/{taskId}
• Response: HTTP 200 with full task object

---

Error Handling

| Error | Solution | |-------|----------| | BEAM_API_KEY not found | Add to .env file | | 401 Unauthorized | Verify API key is valid | | 404 Not Found | Task ID doesn't exist |

---

Related Skills

• beam-get-agent-analytics - Get agent performance metrics
• beam-debug-issue-tasks - Debug failed tasks with Langfuse traces
• beam-retry-tasks - Retry failed tasks