Execution History & Log Schema

LoopCLI records every loop run so you can audit results, spot failures, and measure usage. Each execution is stored with a rich payload that ties the run back to the project, user, connectors, and action counts.

Schema Overview

Each row in the execution_history datastore includes:

id – unique execution UUID.
organization_id – owning org/workspace.
project_id – project that scoped the loop.
loop_id, loop_name, loop_label – the loop definition at execution time.
triggered_by – user UUID or API token that kicked off the run.
initiator_type – user, cli, scheduler, or webhook.
status – queued, running, success, error, timeout, cancelled.
started_at, completed_at – timestamps (UTC ISO-8601).
actions_used – total LoopCLI actions consumed during the run.
duration_ms – wall-clock duration in milliseconds.
connector_ids – array of connectors touched (Stripe, Slack, etc.).
secret_slugs – Vault secrets referenced.
error_message / error_stack – populated when a step fails.
step_results – JSON blob capturing per-step output (HTTP status, CLI stdout pointer, etc.).
metadata – free-form JSON (schedule window, retry attempt, scheduler node).

CLI Commands

LoopCLI provides several commands for viewing execution history:

List Recent Executions

loopcli loop executions

Lists recent loop executions with filters:

# Filter by loop
loopcli loop executions --loop enrich-leads

# Pagination
loopcli loop executions --page 1 --limit 20

# JSON output
loopcli loop executions --json

Interactive Mode: In TTYs, opens a visual history dashboard with ↑/↓ to inspect, n/p to paginate, q to exit.

Plain Mode: Use --plain or set LOOPCLI_SKIP_VISUAL=1 for traditional text output.

View Execution Details

loopcli loop execution exec_01HXYZ...

Shows detailed information about a specific execution:

Status and duration
Per-step timeline
Errors and stack traces
Actions consumed

Interactive Mode: Opens a detail screen (status, timeline, payload, per-step output) in TTYs. Press enter or q to exit.

JSON Output: Add --json flag for machine-readable output.

Browse Local CLI Logs

loopcli loop logs

Lists saved CLI stdout/stderr captures from local executions (stored in .loopcli/logs/).

Options:

--loop <name> – filter by loop name
--step <name> – filter by step name
--stream <stdout|stderr> – filter by stream type
--limit <n> – limit number of results
--latest – open the newest log immediately
--plain – print file paths instead of interactive view

Interactive Mode: Browse files and open them in-view with arrow keys.

Example:

# View latest log
loopcli loop logs --latest

# View specific log file
loopcli loop logs enrich-leads-fetch-lead-stdout-1699564800.log

Wait for Execution Completion

loopcli loop wait exec_01HXYZ...

Polls an execution until it completes. Useful when you queue runs from CI/CD and want to monitor them separately.

Options:

--interval <ms> – polling frequency (default: 2000ms)
--timeout <ms> – abort waiting after specified time
--json – print final execution JSON result

API Access

Query the REST endpoint directly:

GET /api/projects/{projectId}/executions?loop={loopId}&status=error&limit=50
Authorization: Bearer <loopcli token>

Query Parameters:

loop – filter by loop ID
status – filter by status (queued, running, success, error, timeout, cancelled)
limit – number of results (default: 50, max: 200)
page – pagination offset

Response Format:

{
  "success": true,
  "data": {
    "executions": [
      {
        "id": "exec_01HXYZ...",
        "loop_name": "enrich-leads",
        "status": "success",
        "duration_ms": 1234,
        "actions_used": 5,
        "started_at": "2025-11-05T12:00:00Z",
        "completed_at": "2025-11-05T12:00:01Z",
        "step_results": [...]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 142
    }
  }
}

Authentication requires a valid LoopCLI token or dashboard session cookie.

Dashboard Access

The dashboard includes an execution history page at https://app.loopcli.com/history.

The dashboard currently provides basic execution viewing. For advanced filtering and data export, use the CLI commands or API endpoints documented above.

Common Use Cases

Check Recent Failures

# CLI
loopcli loop executions --status error

# API
curl "https://app.loopcli.com/api/projects/$PROJECT_ID/executions?status=error" \
  -H "Authorization: Bearer $TOKEN"

Monitor Specific Loop

loopcli loop executions --loop enrich-leads

Debug Local Execution

# Run with verbose logging
loopcli loop run enrich-leads --verbose

# View saved logs
loopcli loop logs --loop enrich-leads --latest

Export Execution Data

# Get JSON output
loopcli loop executions --json > executions.json

# Or via API
curl "https://app.loopcli.com/api/projects/$PROJECT_ID/executions?limit=200" \
  -H "Authorization: Bearer $TOKEN" > executions.json

Troubleshooting

No Executions Showing

Ensure you're authenticated: loopcli auth whoami
Check you're in the correct project: loopcli project list
Verify the loop has been run at least once

Old Local Logs Missing

Local logs in .loopcli/logs/ are not backed up to the cloud
Only cloud executions are queryable via loopcli loop executions
Local execution logs are stored separately and browseable via loopcli loop logs

API Returns 403

Token may be expired, run loopcli auth login
Verify you have access to the project
Check project ID is correct