Skip to main content

Executions & Monitoring

Every time a workflow runs — whether triggered manually, by webhook, by schedule, or by an event poller — OrcFlows creates an execution: a Temporal workflow run plus a row in the executions table tracking its status, trigger data, input/output, and timing.

Listing & inspecting executions​

EndpointPurpose
GET /api/v1/executionsList executions for the tenant (filterable by workflow, status).
GET /api/v1/executions/visibilitySearch via Temporal's visibility store (e.g. ExecutionStatus = "Running").
GET /api/v1/executions/{id}Summary: status, trigger type/data, input/output, timestamps.
GET /api/v1/executions/{id}/detailFull Temporal event history with per-step input/output, expandable attributes, and friendly event names.
GET /api/v1/executions/{id}/streamServer-Sent Events stream of live status updates (registered outside the request timeout middleware).

The execution detail page in the dashboard renders the Temporal event history as a timeline: each step shows its config, resolved inputs, raw output, duration, and — for AI nodes — token usage and cost.

Step statuses​

Each step execution has a status: pending, running, completed, failed, or skipped (when condition/branch_deps evaluate falsy). Sensitive values (secrets, tokens) are redacted in the displayed payloads (redactSensitive).

Cost tracking​

llm and agent nodes return input_tokens, output_tokens, and cost_usd in their step output, computed from a per-model pricing table (internal/nodes/ai/llm.go). The execution detail page shows a cost badge per AI step and a total-cost strip for the whole run — useful for monitoring spend on agent-heavy workflows.

Retrying & resuming​

POST /api/v1/executions/{id}/retry starts a new execution that resumes from the point of failure: completed step outputs from the failed run are passed as PreloadedOutputs so they're reused rather than re-executed (important for steps with side effects, like sending an email).

Cancelling​

POST /api/v1/executions/{id}/cancel cancels the underlying Temporal workflow. In-flight activities are interrupted; already-completed steps keep their results.

Signals & human-in-the-loop​

POST /api/v1/executions/{id}/signal sends a named Temporal signal with arbitrary JSON data to a running execution — this is the mechanism behind Human-in-the-Loop approvals, and can also be used to push external events into a long-running workflow (e.g. a voice session).

Feedback on step outputs​

POST /api/v1/executions/{id}/steps/{stepId}/feedback lets a user rate/annotate a step's output (e.g. thumbs up/down on an LLM response) — useful for building eval datasets from real traffic.

For a more direct path, Save as test case on the execution detail page copies that execution's real trigger payload straight into an evaluation dataset row, turning a bug report or a flagged bad response into a permanent regression test in one click.

Workspace files​

Workflows that generate files (PDFs, screenshots, CSV exports, code-execution artifacts) write them to the workspace file store (S3/MinIO), namespaced by execution ID:

  • GET /api/v1/workspaces/runs/{exec_id}/files — list files produced by a run.
  • GET /api/v1/workspaces/runs/{exec_id}/files/* — download a specific file.
  • GET /api/v1/files/{id}/{filename} — public download link for files explicitly shared (protected by a 128-bit UUID).

Workflow health​

  • GET /api/v1/workflows/{id}/health — recent success/failure rate and last-run status for one workflow.
  • GET /api/v1/workflows/health — bulk health summary across all workflows, used for the dashboard's health overview.

Audit log​

Significant actions (workflow create/update/delete, secret changes, signals sent, role changes, etc.) are recorded in the audit_events table and exposed via GET /api/v1/audit (admin/owner only).

Next​