Zum Hauptinhalt springen

Workflow Runs

A run keeps its exact workflow version, dependencies and captured input. Publishing another version or editing the source record does not change an admitted run. Inspection requires workflows:manage. Following a Task or record link still requires that resource's ordinary permissions.

Automatic admission and record validation​

Record creation and updates admit matching enabled publications in the same transaction as the record change. Pause, deletion and publication changes serialize with admission: a run admitted first retains its pinned publication; a lifecycle change committed first governs subsequent admission. Changed-field filters count toward admission limits only when at least one configured field changed. Exceeding the configured per-record or per-transaction run limit returns 409 and rolls back the write.

The complete captured record and publication must fit the 256 KiB run-input limit. Exceeding it returns 422 validation-failed, with #/data for a single record or #/items/{index}/data for a batch item. The entire record transaction, including sibling records and run admissions, rolls back. Reduce the record data or its display-template expansion, or simplify the workflow publication. Manual starts report the same limit at #/record_id.

Before executing the first step, the Worker checks all frozen record dependencies, including those declared by Scripts and Agents. Known incompatibilities fail the run before it creates Tasks or performs other step effects; an automatic run failure does not roll back the source record write. The affected step is marked failed, while unexecuted steps are skipped. The run and affected step expose record_schema_changed, record_access_denied, or record_dependency_unavailable as their sanitized error_code. Review the dependency and republish when its schema or scope changes. Execution-time checks still apply: a dependency can change after preflight, and earlier committed effects remain if a later step then fails.

Find runs​

Use GET /api/v2/workflow-runs across workflows, or GET /api/v2/workflows/{workflow_id}/runs for one workflow. /workflow-runs is a collection only; run details and controls always include the owning workflow UUID.

Both collections accept:

QueryMeaning
version_idExact pinned publication; it must belong to the selected workflow, if supplied.
statusqueued, running, succeeded, failed, timed_out, cancelled or terminated.
object_id, record_idCaptured trigger identities, including after the object or record is deleted.
created_from, created_toInclusive lower/exclusive upper creation timestamps, RFC 3339 with an explicit offset. The upper bound must be later.
page, sizeZero-based page and size 1–100; defaults 0 and 20.
sortOne created_at or id criterion, optionally :asc or :desc; default created_at:desc, with stable ID ordering for ties.

The cross-workflow collection also accepts workflow_id. Lists use the standard items and page envelope and return metadata without decrypting captured inputs, including workflow_name when the owning workflow has not been deleted. Unknown query keys, malformed values and invalid bounds return 422. Unknown workflow/version filters or mismatched workflow/version ownership return 404.

GET /api/v2/workflows/WORKFLOW_UUID/runs?version_id=VERSION_UUID&status=failed&page=0&size=20

Inspect one run and its steps​

GET /api/v2/workflows/{workflow_id}/runs/{run_id}
GET /api/v2/workflows/{workflow_id}/runs/{run_id}?include=version
GET /api/v2/workflows/{workflow_id}/runs/{run_id}/steps
GET /api/v2/workflows/{workflow_id}/runs/{run_id}/steps/{step_execution_id}

Use the workflow_id and run id returned by the list. Each step has its own execution id and a separate node_id identifying the authored graph node. Pass the execution id as step_execution_id; do not substitute or derive it from node_id. Every nested identity must belong to the stated parents and tenant. Mismatches return 404 before private step content is loaded. Retained runs remain inspectable after the workflow parent is deleted.

Run detail includes all logical steps in the pinned graph. The step collection returns {"items":[...]} without pagination because the current graph is bounded to 20 actions. include=version adds the exact pinned publication, including its step and trigger descriptions; no other expansion is supported.

Customer history retains:

  • Captured trigger input and resolved Task inputs.
  • Accepted Script/Agent input and output, bounded Script logs and sanitized failures.
  • Committed Task UUIDs and captured task_output for native read/create/update steps, including the complete fixed location or null for a non-Visit Task.
  • Record results, question answers, branch decisions and durable wait times.
  • An ordered interactions list per step, retaining every Agent question and its Task-owned answer. Static question steps have at most one interaction; Agent clarification allows at most ten.
  • Confirmed Agent token categories, web request counts and estimated provider cost, plus pending/unknown usage.
  • Final validated Agent source links in code_execution.agent.citations, independent of transcript expiry.

A reached If/Else has succeeded status and a recorded condition_matched value. It selects its matching or otherwise path; steps on the unselected path are skipped. Connect either path to End for successful early completion. Earlier effects remain after the run ends.

Compact Script tool results retain Task IDs for committed create/update/complete operations. Direct record operations retain their captured record result. These business effects remain visible if a later step fails, and their references do not depend on loading Agent event pages. Accepted final Agent output and usage also remain independent of conversational retention.

Run and step statuses are updated directly as the workflow engine executes, so a terminal run status includes its final step outcomes. Pending or unknown usage must not be treated as zero. Provider cost estimates are distinct from customer billing. agent_usage aggregates Agent steps; each code_execution.agent also exposes web_search_requests, web_fetch_requests and unknown_web_usage_calls. Counts are confirmed observations, so a nonzero unknown count means they are incomplete. estimated_web_cost_microusd is the web fee component already included in estimated_cost_microusd; do not add it again. Either estimate is omitted when its cost cannot be established.

Read retained Agent activity​

GET /api/v2/workflows/{workflow_id}/runs/{run_id}/steps/{step_execution_id}/events?page=0&size=20

The event collection uses items and page, defaults to 20 items and permits at most 100 per page. Events have a stable id and zero-based sequence within the step. Current event types are:

  • assistant_turn: visible message segments, permitted tool proposals and native web_activity segments, in their original order.
  • tool_result: a committed READ outcome with retained input/output and recognized Task/record lookup links.

Message segments include validated citations. Native web activity reports its selected tool, pending, completed or failed status, query or URL when available, and validated sources. It omits raw retrieved bodies, provider identifiers and opaque citation indexes. These activity segments expire with the transcript; accepted final citations remain attached to the output.

A tool proposal does not prove that the tool ran. Agent tools are READ-only; their lookup links are retained activity, rather than additional committed business effects. Non-Agent steps currently return an empty event collection.

Each event includes availability and expires_at:

AvailabilityDisplay meaning
retainedRecognized content is complete and available until the stated deadline.
partialContent is pending, missing, malformed, or only a safe subset is available.
expiredConversational content and lookup links are unavailable.

Expired content is omitted even if maintenance has not physically pruned it. Tool conversational input/output follows its parent turn's retention boundary. Never reconstruct unavailable content from a raw provider envelope. Private instructions, internal reasoning, provider identifiers and raw request/response documents are absent from these customer representations. Reads do not call an AI provider, execute a tool or restart a workflow.

Start and cancel deliberately​

POST /api/v2/workflows/{workflow_id}/runs admits an enabled manual_record publication for an accessible record. Send request_id, the reviewed version_id and record_id. Admission requires workflows:manage, objects:records:read and the record's normal access; executable dependencies also require workflows:code:execute. The response is 202 with the run and its absolute nested Location. Reuse the same request_id only when retrying the same intended run. A new ID deliberately requests another execution and can repeat business effects.

POST /api/v2/workflows/{workflow_id}/runs/{run_id}/cancel requires workflows:manage and no body. It records cancellation, prevents new effects and closes pending question Tasks, then delivers cancellation asynchronously. Pending cancellation returns 202; an already observed terminal run returns 200 unchanged. Repeating the request is idempotent. Inspect cancellation_requested_at and the actual run status: concurrent completion can win. Previously committed effects remain.

System support diagnostics​

Customer REST and MCP do not expose internal step operations, retry counters, delivery records, provider documents or reservation mechanics. These require the separate system-admin API under /admin/v1/tenants/{tenant_id}/workflows/{workflow_id}/runs/{run_id}. Customer workspace admin roles and workflows:manage do not grant that access.

System inspection validates the path tenant and every nested owner, uses bounded retained evidence, and audits successful sensitive reads with the actual system-admin actor. It does not impersonate a tenant user or execute recovery actions. Expired provider content remains unavailable there too.