Summarize a range of runs

Since v2026.10.8

GET/api/runs/range

Summarizes the runs in a range: causes of failure, days, triggers and the busiest workflows.

Needs an API token with the Read permission for runs (run:read).

Parameters

Query

workflowIdOptional · UUID: One workflow’s runs.
environmentOptional · string: production (the default), test or all.
windowOptional · string: 24h, 7d, 30d, 90d or all (the default). Not with from or to.
tzOptional · string: A time zone name, such as Europe/Berlin, for “today” and the days. Unknown or left out: UTC.

What are the rarely used parameters?

triggerTypeOptional · string: How it began: manual, webhook, cron, poll, error, run_finished, event, api, mcp or subflow.
tagOptional · string: Runs with exactly this tag, added by the Tags app.
fromOptional · time: Runs started at or after this time (RFC 3339).
toOptional · time: Runs started before this time. After from.
qOptional · string: Up to 200 characters. Finds runs whose ID starts with it, or whose workflow name or error has it, ignoring case.
reasonOptional · string: Up to 200 characters. Runs whose error has it, ignoring case.
groupOptional · string: A failure group’s key, from Group failed runs.

Read it

byCause holds the 5 biggest failure groups (see Group failed runs), byWorkflow the 10 busiest workflows. byDay uses the days of tz.

slowerThanUsual counts finished runs that took at least slowerFactor times (3) their workflow’s usual time.

Responses

200OK
The summary.
400VALIDATION_ERROR
A filter has a value it doesn’t take. The message names it.
403FORBIDDEN
The token lacks the Read permission for runs.
500INTERNAL_ERROR
The summary 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 runs

URL="$GORUNNER/api/runs/range?window=7d&tz=Europe/"
URL="${URL}Berlin"
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/runs/` +
    `range?window=7d&tz=Europe/Berlin`,
  {
    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/runs/range",
    params={
      "window": "7d",
      "tz": "Europe/Berlin",
    },
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

Response · 200 OK, shortened

json

{
  "data": {
    "runs": 120,
    "failed": 10,
    "failedWorkedOnRetry": 4,
    "slowerThanUsual": 2,
    "slowerFactor": 3,
    "byCause": [
      {
        "key": "gAAAAB…",
        "workflowId": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
        "workflowName": "Order intake",
        "step": "Forward to fulfilment",
        "reason": "the service answered 503",
        "count": 10
      }
    ],
    "byDay": [
      {
        "day": "2026-10-25",
        "from": "2026-10-25T00:00:00+02:00",
        "runs": 15,
        "failed": 1
      },
      "…"
    ],
    "byTrigger": [
      {
        "triggerType": "webhook",
        "runs": 98,
        "failed": 10
      }
    ],
    "byWorkflow": [
      {
        "workflowId": "3b1e5c2a-7d4f-4e8b-a1c6-5f2d9b0e7a31",
        "workflowName": "Order intake",
        "runs": 64,
        "failed": 10
      }
    ]
  }
}

Every field

It takes no body.

Response · 200 OK

dataobject
runsinteger
failedinteger
failedWorkedOnRetryinteger
slowerThanUsualinteger
slowerFactorinteger
byCausearray of objects: The biggest failure groups (at most 5), biggest first.
keystring: The failure group’s key (GET /api/runs?group={key}).
workflowIdUUID
workflowNamestring
stepstring: The failed step’s display name; absent when the messages name no step.
reasonstring
countinteger
byDayarray of objects: Each local day in tz with runs in the range.
daystring
fromtime: The day’s own start.
runsinteger
failedinteger
byTriggerarray of objects: Runs and failures by the run’s own trigger type (as GET /api/runs?triggerType).
triggerTypestring
runsinteger
failedinteger
byWorkflowarray of objects: The 10 busiest workflows.
workflowIdUUID
workflowNamestring
runsinteger
failedinteger