Skip to content
FLORA FLORA API

Run canvas nodes

POST
/workspaces/{workspaceId}/projects/{projectId}/nodes/run
 
import { FloraClient } from '@flora-ai/flora';


const client = new FloraClient({ apiKey: process.env['FLORA_API_KEY'] });


const canva = await client.projects.canvas.runNodes({
  workspaceId: '<workspaceId>',
  projectId: '<projectId>',
  node_ids: [
    'n3',
  ],
});
console.log(canva);

Runs generation nodes that already exist on a project canvas. Each node runs with the model, prompt, parameters and wired upstream inputs it already carries — this endpoint supplies nothing but ids, so configure a node with a canvas changeset first. Timeline (video editor) nodes render their saved draft recipe through the video editor render pipeline instead of the generation pipeline: the started entry carries a render-job run_id (poll it like any run) with no model or cost estimate, and the spend settles on timeline render usage rather than generation credits. GENERATION RUNS SPEND THE WORKSPACE’S CREDITS IMMEDIATELY: there is no confirmation step and no dry run, and the charge lands whether or not you poll the result. Nodes are addressed by the short id or node UUID the project graph endpoint reports, and each entry echoes the identifier you sent. The response returns as soon as every run has an id — it never waits for the generations, which continue in the background — so poll each run_id for status and output. Nodes requested in one call run in dependency order: connected nodes run children before parents, so a chain can be started in a single request, and independent nodes run in parallel. A node that cannot run is reported as its own skipped entry with a machine-readable reason and never fails the rest of the batch; only an empty or oversized node_ids list, a project that does not exist in the workspace, or denied write access fail the whole request. Credits are not checked up front: insufficient credits surface on the individual run, not on this request. Known limits compared with running a node in the Flora editor: automatic model routing covers image nodes only, an element node with several assets counts as one input, and collections, batch fan-out, per-run parameter overrides and multi-model selections are not supported. Mutating public API requests support an optional Idempotency-Key header for client retries; duplicate keys within two hours return idempotency_duplicate.

Error responses use the standard error body.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
workspaceId
required

Workspace identifier

string
/^ws_\S+$/

Workspace identifier

projectId
required

Project identifier

string
/^prj_\S+$/

Project identifier

Request Body required

Section titled “Request Body required ”
Media type application/json
object
node_ids
required

Nodes to run, addressed by the short id or node UUID the project graph endpoint reports. Between 1 and 50 per request.

Array<string>
>= 1 items <= 50 items

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Runs started.

Media type application/json
object
project_id
required

Project identifier

string
/^prj_\S+$/
runs
required

One entry per requested node, in the order the request listed them.

Array<object>
<= 50 items
object
node_id
required

The identifier supplied for this node, echoed verbatim: a short id in is a short id out

string
>= 1 characters
status
required

Whether this node’s generation was started or could not run. Skipped nodes carry a reason and never charge.

string
Allowed values: started skipped
run_id

Run identifier to poll for this node. Present only when status is started.

string
/^run_\S+$/
type

Run type. Present only when status is started.

Allowed value: generation
model
Any of:
object
model_id
required

Model identifier

string
>= 1 characters
estimated_seconds
Any of:
integer
charged_cost
Any of:
number
poll_url

URL to poll this run. Present only when status is started.

string format: uri
reason

Why the node did not run. Present only when status is skipped. node_not_found: no node on this canvas answers to that id. node_not_executable: the node generates nothing — action nodes run through the action run endpoint. node_locked: the node is locked on the canvas. no_model_configured: the node has no model set. generation_already_running: a generation for this node is already in flight. run_failed_to_start: the run could not be started for this node — the rest of the batch is unaffected, retry this node. video_generation_not_available: the workspace’s plan does not include video generation. timeline_no_document: the timeline node has no document yet — write one with a changeset update carrying document, then run it again. timeline_not_entitled: the workspace’s plan does not include the Timeline Editor. video_editor_run_not_supported: deprecated, no longer emitted; kept for clients that enumerate it.

string
Allowed values: node_not_found node_not_executable node_locked no_model_configured generation_already_running run_failed_to_start video_generation_not_available timeline_no_document timeline_not_entitled video_editor_run_not_supported
message

Human-readable explanation of the skip. Present only when status is skipped.

string
Example 
{
  "project_id": "prj_abc123",
  "runs": [
    {
      "node_id": "n3",
      "status": "started",
      "run_id": "run_abc123",
      "type": "generation",
      "model": {
        "model_id": "t2i-flux-2-pro"
      },
      "reason": "node_not_found"
    }
  ]
}