FactorAI

Workflow and Run lifecycle

How Workflows, Workflow Runs, Runs, Revisions, and Attempts relate.

Use a Workflow when you want a saved objective to coordinate work over time. Use a Run when you want one independently dispatched unit of work. This page shows how the objects relate and where each lifecycle is controlled.

How the objects relate

approved dispatchTeamProjectWorkflowImmutable WorkflowRevisionWorkflow RunWorkflow TaskRunImmutable Run RevisionRun AttemptChat
  • A Workflow is a saved objective with immutable revisions. A Workflow Run is one execution of that objective and owns its trigger occurrences and tasks.
  • A Run is independently dispatched work with its own policy, budget, and history. A standalone Run does not need a Workflow.
  • A Run Revision freezes the prompt, input, model, tools, capabilities, and context for one Run. An Attempt executes that revision and can resume after an interruption.
  • A Chat is a long-lived conversation. An approved chat action can dispatch a Run, while a Workflow can dispatch Runs for its tasks.

Workflow lifecycle

  1. Publish a Workflow with POST /v1/workflows. Publication creates the Workflow and its first immutable revision.
  2. Start it with POST /v1/workflows/{workflowId}/start. Choose finite for work that drains to completion or continuous for a Workflow that stays open to later trigger occurrences.
  3. Inspect the orchestration with GET /v1/workflow-runs/{workflowRunId}. A Workflow Run moves through initializing, active, or paused before it reaches a terminal status.
  4. Control it with POST /v1/workflow-runs/{workflowRunId}/control. The available controls are pause, resume, cancel, and finish; each command carries an idempotency key and a reason.

The terminal Workflow Run statuses are completed, failed, cancelled, and failed-validation. A failed-validation result means validation stopped the run before root settlement.

Run lifecycle

An API, UI action, schedule firing, or approved Chat action can dispatch a Run. The dispatch creates its immutable Run Revision and first Attempt. The Attempt executes the revision, records its outputs and usage, and can be retried on the same revision or rerun as a fresh Run.

Use GET /v1/runs/{runId} to read a Run and its execution history. The workflow guide shows a complete API example that starts a Workflow and reads its resulting Workflow Run.

Inspect a Workflow Run

Set the API origin and a key with the permissions described in API keys, then list visible Workflow Runs:

export API_ORIGIN="https://api.factorai.ai"
export API_KEY="<your API key>"

curl -sS "$API_ORIGIN/v1/workflow-runs?limit=20" \
  -H "Authorization: Bearer $API_KEY" | jq '.workflowRuns[] | {
    id,
    status
  }'

The nextCursor value is opaque. Pass it back as cursor to read the next page. See the API overview for authentication, pagination, errors, and permission requirements.

Next steps