List workflows

GET/api/workflows

Returns a page of the workspace’s workflows, with filters and a sort.

Needs an API token with the Read permission for workflows (workflow:read).

Parameters

Query

pageOptional · integer: The page, from 1. Below 1, or not a number, reads as 1.
limitOptional · integer: Workflows a page, 1 to 100. The default is 20; anything else reads as 20.
qOptional · string: Finds words in the name, description, tags and the apps used, by id or name (stripe, Google Sheets). Ignores case. Not step names.
statusOptional · string: draft, active, paused or failing: live, and its latest finished production run failed.
tagOptional · string: Keeps workflows with this tag, ignoring case. One tag a call.
folderOptional · string: A folder’s ID, or none for workflows in no folder. Only workflows filed directly in it.
sortOptional · string: updated (the default, newest first), name (A to Z), lastrun (latest run first) or status (paused, live, then drafts).
viewOptional · string: summary leaves out each row’s definition and runs7d. Every row has summary: the trigger, the apps, the step count and the steps to set up.

What are the rarely used parameters?

lastRunStatusOptional · string: Keeps workflows whose latest production run is in this state: completed, failed, running, pending, cancelled or paused.
idsOptional · string: Up to 100 workflow IDs, separated by commas. Answers just those, as one page, and ignores every other filter.
countsOptional · string: true adds counts: the matching workflows by state, and how many are failing. Not with ids.

What a row holds

Without view=summary, each row holds its whole draft definition, so a page can run to hundreds of kilobytes. Ask for the summary when you only list them.

lastRun is the latest production run, and test runs never count. A failing row adds failingSince and failingRun, the run that made it fail.

A token without the Read permission for runs gets only status and startedAt of those runs, and no failingSince.

No row holds webhookToken. Read it with Get a workflow.

Responses

200OK
A page of workflows. A page past the end has no rows, and pagination is still filled in.
400VALIDATION_ERROR
folder isn’t a folder ID or none, ids isn’t a list of up to 100 IDs, or status, lastRunStatus, sort or view isn’t one of its values.
403FORBIDDEN
The token lacks the Read permission for workflows.
500INTERNAL_ERROR
The list couldn’t be read. Try again.

Any call can also answer: 401 UNAUTHORIZED · 401 TOKEN_ENDED · 403 TOKEN_SURFACE_OFF · 403 FEATURE_OFF · 403 EMBED_NOT_ALLOWED · 403 EMBED_NOT_AVAILABLE · 403 ACCOUNT_SUSPENDED · 429 RATE_LIMITED · 503 BUSY · 503 PAUSED · 503 SERVICE_UNAVAILABLE. See Errors.

Request

GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…"  # needs Read for workflows

URL="$GORUNNER/api/"
URL="${URL}workflows?status=active&view=summary&limit=50"
curl "$URL" \
  -H "Authorization: Bearer $GORUNNER_TOKEN"

const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;

const res = await fetch(
  `${GORUNNER}/api/` +
    `workflows?status=active&view=summary&limit=50`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const { data } = await res.json();

import os, requests

GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]

res = requests.get(
    f"{GORUNNER}/api/workflows",
    params={
      "status": "active",
      "view": "summary",
      "limit": 50,
    },
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

Response · 200 OK, shortened

json

{
  "data": [
    {
      "id": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
      "name": "Order intake",
      "status": "active",
      "triggerType": "webhook",
      "hasUnpublishedChanges": false,
      "folderId": "7a2c9e41-5b3d-4f08-a6e1-2d9c4b7f0e13",
      "tags": [
        "orders"
      ],
      "createdByName": "Ada Lovelace",
      "updatedAt": "2026-10-24T16:40:00Z",
      "failing": false,
      "summary": {
        "trigger": {
          "pieceId": "webhook",
          "actionId": "catch_webhook",
          "displayName": "Catch Webhook"
        },
        "pieces": [
          {
            "id": "webhook",
            "name": "Webhook"
          },
          {
            "id": "http",
            "name": "HTTP Request"
          }
        ],
        "stepCount": 1,
        "needsSetup": 0
      },
      "lastRun": {
        "id": "8f0c41d2-6b7e-4c1a-9d3f-2a5b7c9e1f04",
        "status": "completed",
        "startedAt": "2026-10-25T08:59:58Z",
        "finishedAt": "2026-10-25T09:00:00Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}

Every field

It takes no body.

Response · 200 OK

dataarray of objects

[] when the requested page is past the last one.

idUUID

namestring

descriptionstring

definitionobject

The workflow definition, and the single most important shape in this API.

A workflow definition: its fields are in Workflow definition.

statusstring

draft = never published. active = live, triggers registered and the webhook URL reachable. paused = was live, now switched off. Server-owned: it moves only through publish/unpublish, never through a create or update body.

One of draft, active, paused.

triggerTypestring

Mirrors definition.trigger.type for dispatch. Derived server-side from the definition by every update and publish, so treat it as read-only in practice. A create that sends its own value keeps it until then, unchecked.

One of manual, cron, webhook, callable, event, error, run_finished, poll.

cronExpressionstring or null

Nothing derives or reads this: the schedule runs from the trigger’s own config, and nextRunAt projects from it too. Null unless a caller wrote one with PUT /api/workflows/{id}.

webhookTokenstring or null

The secret segment of the public webhook URL. Made by the first update of a webhook workflow, or at publish; absent until then (so absent in the answers of create, duplicate and import). Returned ONLY to a caller holding workflow:run: by GET /api/workflows/{id} and in the answers of update, publish, unpublish and restore (rotate answers it to its caller). It is never present on a list row, an export or a version snapshot. It is a bearer capability against an unauthenticated endpoint — possessing it is the ability to fire this workflow in production. Rotate it with POST /api/workflows/{id}/webhook/rotate.

latestVersionIdUUID or null

The published snapshot production executes. Absent means nothing has ever been published.

definitionRevinteger

Optimistic-lock revision, bumped by every definition save. Populated by GET /api/workflows/{id}, by the update response and by the answers of create, duplicate and import; absent (0) on list rows. Send it back as expectedRev on an update to refuse a clobbering write.

hasUnpublishedChangesboolean

The draft has moved ahead of the published version. Computed on the single-workflow read and on every list row; always false for a workflow never published.

folderIdUUID or null

Absent/null = uncategorized. Changed only through PUT /api/workflows/{id}/folder.

tagsarray of strings

Changed only through PUT /api/workflows/{id}/tags or the bulk addTags operation — never through the workflow update body.

testPayloadsobject or null

The saved test-fixture library, stored outside the definition so publish and version restore never reset it.

pinnedDataobject or null

The pin library ({"pins": {"<stepName>": {"data": …, "pinnedAt": …, "configHash": …, "staleAt": …, "pieceId": …}}}). A pinned step emits its fixture instead of executing, and only on test runs. configHash, staleAt and pieceId are the server’s: a step whose config changed keeps its pin marked stale, and a stale pin is not replayed (the step runs); a step whose app was replaced loses it.

workspaceIdUUID

Stamped from the credential’s scope; never accepted from a request body.

orgIdUUID

createdByUUID or null

createdByNamestring

List rows only: the creator’s name, else their email address. Absent when the creator is unknown or not a member of the organization (staff who built it on a support visit, someone since removed), and on every row for an embedded person whose installation switched presence off (an embedded person is never told an address).

createdAttime

updatedAttime

When the workflow itself was last edited. Publishing, pausing, tagging and filing it are not edits and leave it alone.

failingboolean

List rows only: the workflow is live (status: active) and its latest FINISHED production run (one that worked or failed) failed. A later run that is waiting, running, held or was cancelled changes nothing, and test runs never count. A paused or draft workflow is never failing.

failingSincetime

Only on a failing row: when the first production run failed after the last one that worked (runs cancelled, held or running in between neither break nor begin the streak). Left out for a caller without run:read.

failingRunobject

Only on a failing row: the run that decided it, its latest finished production run, with why it failed. It is lastRun unless a later run is waiting, running, held or was cancelled. Without run:read it carries status and startedAt alone.

idUUID

statusstring

One of failed.

startedAttime

finishedAttime or null

errorobject

Why it failed, as lastRun.error says it.

stepstring or null

stepKeystring or null

messagestring

summaryobject

List rows only: what a list draws instead of the definition.

triggerobject or null

The chosen trigger; null while none is chosen.

pieceIdstring

actionIdstring

displayNamestring

piecesarray of objects

The apps the workflow uses, each once, in walk order (the trigger first), with their display names.

idstring

namestring

stepCountinteger

Steps after the trigger, across branch arms, loop bodies and error paths.

needsSetupinteger

Steps (and a chosen trigger) the editor marks to configure: valid: false, or no app and action chosen.

runs7darray of integers

List rows without view=summary only: counted runs per UTC day over the last seven days, oldest first (production runs that are not a sub-flow’s, cancelled runs left out).

nextRunAttime

Next fire time of an active schedule workflow, projected from its cron in the trigger’s own timezone. Populated by the list endpoint.

lastRunobject or null

The most recent PRODUCTION run’s outcome (test runs never count). Populated on list rows only. Without run:read it carries status and startedAt alone.

idUUID

finishedAttime or null

errorobject

Only when status is failed: why.

stepstring or null

The display name of the step it failed at; null when the reason names no step.

stepKeystring or null

messagestring

The reason’s first clause, at most 160 characters.

statusstring

One of pending, running, completed, failed, cancelled, paused.

startedAttime

paginationobject

Pagination block returned alongside a workflow list.

pageinteger

limitinteger

The limit ACTUALLY applied after coercion, not necessarily the one you asked for.

totalinteger

Total matching workflows across all pages.

totalPagesinteger

countsobject

Only with counts=true: the list’s workflows by state, and how many of them are failing (live, and the latest finished production run failed), under the same filters as the list.

activeinteger

pausedinteger

draftinteger

failinginteger

What else is on each row?

createdByName is who made it, by name or email. It is missing when that person is unknown or has left. nextRunAt is the next time a live schedule fires. runs7d counts production runs for each of the last 7 days, oldest first, in UTC; cancelled runs and sub-flow runs aren’t counted.

List workflows

Parameters

Query

What a row holds

Responses

Response · 200 OK

Panel