ReferenceFlows API

Runs

A run's steps and outputs, cancelling, and running again with the same input.

Method	Path	Summary
GET	`/api/runs/:id`	Get a run with its steps
GET	`/api/runs/:id/outputs/:nodeId`	A step's whole output from a run (the steps list only has the first 25 items) — for pinning
POST	`/api/runs/:id/cancel`	Cancel a run
POST	`/api/runs/:id/retry`	Run the flow again (as it is now) with the same trigger data

#Get a run with its steps

GET/api/runs/:id

Address: https://<your-org>.brambleit.cloud/flows/api/runs/:id
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Flows.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`run`	object
`run.graph`	any
`run.pending_steps`	array of any
`run.waiting_until`	string (date-time), or null
`run.waiting_on`	array of object
`run.waiting_on[].id`	integer, or null
`run.waiting_on[].kind`	string: "approval" \| "form"
`run.waiting_on[].title`	string
`run.waiting_on[].expires_at`	string (date-time)
`graph`	any
`steps`	array of object
`steps[].id`	integer, or null
`steps[].node_id`	string
`steps[].node_name`	string
`steps[].node_type`	string
`steps[].status`	string: "success" \| "error" \| "waiting"
`steps[].pinned`	any
`steps[].attempt`	integer
`steps[].input_count`	integer
`steps[].output_counts`	array of any
`steps[].input_preview`	any
`steps[].output_preview`	any
`steps[].error`	string, or null
`steps[].logs`	array of any
`steps[].started_at`	string (date-time)
`steps[].finished_at`	string (date-time)

Example response

JSON

{
  "run": {
    "…run": "…",
    "graph": null,
    "pending_steps": [],
    "waiting_until": "2026-11-12T09:30:00.000Z",
    "waiting_on": [
      {
        "id": 42,
        "kind": "approval",
        "title": "Example title",
        "expires_at": "2026-11-12T09:30:00.000Z"
      }
    ]
  },
  "graph": null,
  "steps": [
    {
      "id": 42,
      "node_id": "string",
      "node_name": "Example node name",
      "node_type": "string",
      "status": "success",
      "pinned": null,
      "attempt": 1,
      "input_count": 3,
      "output_counts": [],
      "input_preview": null,
      "output_preview": null,
      "error": "string",
      "logs": [],
      "started_at": "2026-11-12T09:30:00.000Z",
      "finished_at": "2026-11-12T09:30:00.000Z"
    }
  ]
}

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/flows/api/runs/42', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#A step's whole output from a run (the steps list only has the first 25 items) — for pinning

GET/api/runs/:id/outputs/:nodeId

A step's whole output from a run (the steps list only has the first 25 items) — for pinning. Kept for 2 days (the trigger's for 30).

Address: https://<your-org>.brambleit.cloud/flows/api/runs/:id/outputs/:nodeId
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Flows.

Path parameters

Name	Type	Description
`id`required	integer
`nodeId`required	string

Response 200

Field	Type	Description
`outputs`	array of any
`complete`	boolean

Example response

JSON

{
  "outputs": [],
  "complete": false
}

Errors

Status	Message
404	That step didn't run in this run

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/flows/api/runs/42/outputs/string', {
  method: 'GET',
  credentials: 'include',
});
const data = await res.json();

#Cancel a run

POST/api/runs/:id/cancel

Address: https://<your-org>.brambleit.cloud/flows/api/runs/:id/cancel
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Flows.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`ok`	boolean

Example response

JSON

{
  "ok": true
}

Errors

Status	Message
403	Not allowed

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/flows/api/runs/42/cancel', {
  method: 'POST',
  credentials: 'include',
});
const data = await res.json();

#Run the flow again (as it is now) with the same trigger data

POST/api/runs/:id/retry

Address: https://<your-org>.brambleit.cloud/flows/api/runs/:id/retry
Requires: Signed-in browser session (the sso_session / session_id cookies from Bramble sign-in).
Licence: Flows.

Path parameters

Name	Type	Description
`id`required	integer

Response 202

Field	Type	Description
`run_id`	integer

Example response

JSON

{
  "run_id": 7
}

Errors

Status	Message
403	Only the owner can run this flow

Example request

JavaScript

// From a page served by Bramble (uses the signed-in session)
const res = await fetch('/flows/api/runs/42/retry', {
  method: 'POST',
  credentials: 'include',
});
const data = await res.json();

Was this page helpful?