List folders
GET/
Returns every folder in the workspace as one flat list, ordered by name.
Needs an API token with the Read permission for workflows (workflow:read).
Request
It takes no parameters.
Build the tree
The list is flat. Put each folder under the one its parentId names; a folder without one is at the top.
workflowCount, liveCount and failingCount count the workflows filed directly in the folder. The total… counts add every folder under it, at any depth.
In this list, workspaceId and orgId are all zeros. Create a folder answers them filled in.
Responses
- 200OK
The folders, flat. An empty workspace answers
[]. - 403
FORBIDDENThe token lacks the Read permission for workflows.
The folders 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
curl "$GORUNNER/api/folders" \
-H "Authorization: Bearer $GORUNNER_TOKEN"const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const res = await fetch(`${GORUNNER}/api/folders`, {
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/folders",
headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]Response · 200 OK, shortened
{
"data": [
{
"id": "7a2c9e41-5b3d-4f08-a6e1-2d9c4b7f0e13",
"name": "Billing",
"workflowCount": 2,
"liveCount": 1,
"failingCount": 0,
"totalWorkflowCount": 5,
"totalLiveCount": 3,
"totalFailingCount": 1,
"createdAt": "2026-10-25T09:00:00Z",
"updatedAt": "2026-10-25T09:00:00Z"
},
{
"id": "6e9a1c3f-8b2d-4a57-9e0c-3f7b5d1a8c42",
"name": "Invoices",
"parentId": "7a2c9e41-5b3d-4f08-a6e1-2d9c4b7f0e13",
"workflowCount": 3,
"liveCount": 2,
"failingCount": 1,
"totalWorkflowCount": 3,
"totalLiveCount": 2,
"totalFailingCount": 1,
"createdAt": "2026-10-25T09:00:00Z",
"updatedAt": "2026-10-25T09:00:00Z"
}
]
}Every field
It takes no body.
Response · 200 OK
dataarray of objectsidUUIDnamestringTrimmed of surrounding whitespace. At most 255 characters. Create and rename refuse a name a sibling already has, ignoring case (409
NAME_TAKEN); deleting a folder moves its children up and renames a child whose name is taken there (<name> (2)), so siblings never share a name.parentIdUUIDParent folder. Absent/null means a root folder. The list is flat — build the tree from this field.
workspaceIdUUIDOwning workspace. Populated on create; the all-zero UUID in list responses (not selected by the list query).
orgIdUUIDOwning organization. Same caveat as
workspaceId.workflowCountintegerWorkflows filed DIRECTLY in this folder. Does not include workflows in descendant folders.
liveCountintegerlive workflows filed directly in this folder. 0 on a create’s answer.
failingCountintegerfailing workflows filed directly in this folder (live, and the latest finished production run failed). 0 on a create’s answer.
totalWorkflowCountintegerworkflows in this folder and every folder under it, at any depth. 0 on a create’s answer.
totalLiveCountintegerlive workflows in this folder and every folder under it. 0 on a create’s answer.
totalFailingCountintegerfailing workflows in this folder and every folder under it. 0 on a create’s answer.
createdAttimeupdatedAttime