---
title: 'How Workflows Work'
description: 'What a Gravity workflow is made of, drafts and published versions, runs and what they record, and which endpoints work with each.'
---

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](/docs/api/rest/introduction/connections) 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](/docs/api/rest/actions/publish-workflow) makes the draft a new version, and [Update Workflow](/docs/api/rest/actions/update-workflow) with `"isActive": true` turns its triggers on. [List Workflow Versions](/docs/api/rest/actions/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](/docs/api/rest/actions/get-workflow-definition) answers the whole draft as one document, and [Set Workflow Definition](/docs/api/rest/actions/set-workflow-definition) writes it in one call: every trigger and step with its configuration. The [Workflow Building Guide](/docs/api/rest/introduction/workflow-building-guide) is the recommended path start to finish, and [Build a Workflow](/docs/api/rest/introduction/build-a-workflow) covers each part in depth. [Workflow References](/docs/api/rest/introduction/workflow-references) explains how a step reads values from earlier steps, and [Built-in Steps](/docs/api/rest/introduction/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](/docs/api/rest/actions/run-workflow) starts one and answers its id at once; runs execute in the background.
- [Get Run](/docs/api/rest/actions/get-run) follows it, and [Cancel Run](/docs/api/rest/actions/cancel-run) stops it.
- [List Run Steps](/docs/api/rest/actions/list-run-steps) and [List Run Operations](/docs/api/rest/actions/list-run-operations) show what it did.

For monitoring across runs, use [List Workflow Operations](/docs/api/rest/actions/list-workflow-operations) for one workflow or [List Operations](/docs/api/rest/actions/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](/docs/api/rest/actions/get-usage) shows how many you have used this period, [Get Daily Usage](/docs/api/rest/actions/get-usage-daily) day by day, and [Get Usage by Workflow](/docs/api/rest/actions/get-usage-workflows) which workflows used them.