How Workflows Work

A workflow is an automation: a trigger that starts it (a schedule, a webhook, a change in an app) and steps that run in order (app actions, and built-in steps such as Loop, If/Else and Map). Steps nest: a Loop holds the steps it repeats, an If/Else the steps of each branch. Each app step uses a connection to reach its app.

Drafts and versions

A workflow has a draft, which you change, and published versions, which run. Every change to its steps goes to the draft, and each change takes the draft's revision in If-Match so two editors never overwrite each other. Publish Workflow makes the draft a new version, and Update Workflow with "isActive": true turns its triggers on. List Workflow Versions shows the history, and any version can be restored into the draft.

A few trigger settings go live as soon as you save them, as in the editor: a schedule, a webhook's custom URL and a polling interval.

Building one

Get Workflow Definition answers the whole draft as one document, and Set Workflow Definition writes it in one call: every trigger and step with its configuration. The Workflow Building Guide is the recommended path start to finish, and Build a Workflow covers each part in depth. Workflow References explains how a step reads values from earlier steps, and Built-in Steps lists the built-in steps and their settings.

Workflows can also take inputs (values set when it runs) and be grouped with tags.

Runs

Each time a workflow starts, it makes a run. A run records each step it executed, with the exact request the step sent and what the app answered, and every operation: each record it created or updated, and each error or warning.

• Run Workflow starts one and answers its id at once; runs execute in the background.
• Get Run follows it, and Cancel Run stops it.
• List Run Steps and List Run Operations show what it did.

For monitoring across runs, use List Workflow Operations for one workflow or List Operations for workflows in one organization. Each operation includes its workflow and run ids, run start time, run status, and environment id and name. Run metadata is null when its history is no longer retained. Deleted workflows are excluded; when acting in another organization, Embedded runs and operations without retained run metadata are excluded too.

For example, filter with where=createdOn>=2026-11-01;message=like=*FAILED*. The asterisks match messages containing FAILED; FAILED* alone matches only messages starting with it. Use operation createdOn for monitoring windows so operations whose run metadata expired remain eligible.

Run and operation lists default to 100 rows per page. Request limit=1000 and increase offset by the requested page size while meta.pagination.hasNextPage is true. One page is not necessarily the whole result. Use a bounded time window and deduplicate by operation id when collecting successive pages, since offset pagination does not freeze the dataset between requests.

Usage

Runs use tasks, which count toward your plan. Get Usage Summary shows how many you have used this period, Get Daily Usage day by day, and Get Usage by Workflow which workflows used them.