> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/api/reference/canvas/runcanvasnodes.md).

# Run canvas nodes

Run canvas nodes with the FLORA API: POST /workspaces/{workspaceId}/projects/{projectId}/nodes/run.

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.

```http
POST https://app.flora.ai/api/v1/workspaces/{workspaceId}/projects/{projectId}/nodes/run
```

* **Auth:** API key as a bearer token, `Authorization: Bearer $FLORA_API_KEY`. See [Authentication](https://docs.flora.ai/api/platform/authentication.md).
* **TypeScript SDK:** `client.projects.canvas.runNodes()`.
* **Idempotency:** optional `Idempotency-Key` header. See [Idempotency](https://docs.flora.ai/api/platform/idempotency.md).
* **Operation ID:** `runCanvasNodes`.

## Example

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST 'https://app.flora.ai/api/v1/workspaces/ws_abc123/projects/prj_abc123/nodes/run' \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "node_ids": [
    "n3"
  ]
}'
```

{% endtab %}

{% tab title="TypeScript SDK" %}

```typescript
import { FloraClient } from '@flora-ai/flora';

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

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

{% endtab %}
{% endtabs %}

## Path parameters

| Name          | Type   | Required | Description                                                      |
| ------------- | ------ | -------- | ---------------------------------------------------------------- |
| `workspaceId` | string | Yes      | Workspace identifier. Pattern: `^ws_\S+$`. Example: `ws_abc123`. |
| `projectId`   | string | Yes      | Project identifier. Pattern: `^prj_\S+$`. Example: `prj_abc123`. |

## Request body

Required.

| Field      | Type            | Required | Description                                                                                                                           |
| ---------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `node_ids` | array of string | Yes      | Nodes to run, addressed by the short id or node UUID the project graph endpoint reports. Between 1 and 50 per request. 1 to 50 items. |

## Responses

### 201: Runs started.

| Field                      | Type             | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`               | string           | Yes      | Project identifier. Pattern: `^prj_\S+$`. Example: `prj_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `runs`                     | array of objects | Yes      | One entry per requested node, in the order the request listed them. At most 50 items.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `runs[].node_id`           | string           | Yes      | The identifier supplied for this node, echoed verbatim: a short id in is a short id out. At least 1 character. Example: `n3`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `runs[].status`            | string           | Yes      | Whether this node's generation was started or could not run. Skipped nodes carry a reason and never charge. One of: `started`, `skipped`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `runs[].run_id`            | string           | No       | Run identifier to poll for this node. Present only when status is started. Pattern: `^run_\S+$`. Example: `run_abc123`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `runs[].type`              | string           | No       | Run type. Present only when status is started. Always `generation`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `runs[].model`             | object or null   | No       | Endpoint the node is configured for. Null when the node routes its model at run time, so the model is only decided once the run starts.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `runs[].model.model_id`    | string           | Yes      | Model identifier. At least 1 character. Example: `t2i-flux-2-pro`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `runs[].estimated_seconds` | integer or null  | No       | Expected duration of this run, or null when the model is not yet decided. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `runs[].charged_cost`      | number or null   | No       | List price in USD of this node's run at start time, from the node's own parameters and current inputs, before any plan discount; an estimate for usage-priced models. When the run can't be priced from them (the model is picked at run time, an input comes from another node in this request, or pricing was unavailable), the configured model's price at default settings. Null when the model is not yet decided. The amount actually charged is reported on the run itself. At least 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `runs[].poll_url`          | string (uri)     | No       | URL to poll this run. Present only when status is started.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `runs[].reason`            | string           | No       | 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. serving\_provider\_not\_allowed: the node's model is not served by the workspace's allowed inference providers. model\_not\_available\_via\_api: the model exists but is not available via the public API. 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. One of: `node_not_found`, `node_not_executable`, `node_locked`, `no_model_configured`, `generation_already_running`, `run_failed_to_start`, `video_generation_not_available`, `serving_provider_not_allowed`, `model_not_available_via_api`, `timeline_no_document`, `timeline_not_entitled`, `video_editor_run_not_supported`. |
| `runs[].message`           | string           | No       | Human-readable explanation of the skip. Present only when status is skipped.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Errors

Every error has the same body: `error.code`, `error.message`, and `error.fields` on validation errors. See [Errors](https://docs.flora.ai/api/platform/errors.md) for how to recover from each code.

| Status | Code                                         | Meaning                                                                             |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------- |
| 400    | `invalid_json`, `input_validation_error`     | The body isn't valid JSON, or an input failed validation (`fields` lists each one). |
| 401    | `unauthorized`, `invalid_api_key`            | The API key is missing, invalid or revoked.                                         |
| 402    | `insufficient_credits`                       | The workspace balance is too low for this request.                                  |
| 403    | `forbidden`, `paid_plan_required`            | The key can't do this, or the workspace plan doesn't include it.                    |
| 404    | `not_found`                                  | The resource doesn't exist or isn't visible to this key.                            |
| 409    | `idempotency_duplicate`, `revision_conflict` | Duplicate `Idempotency-Key` or a stale `base_revision`.                             |
| 429    | `rate_limited`                               | Too many requests. Back off and retry.                                              |
| 500    | `unknown_error`, `internal_error`            | Something failed on FLORA's side. Retry with backoff.                               |
| 503    | `temporarily_unavailable`                    | Authorization is temporarily unavailable. Retry later.                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/reference/canvas/runcanvasnodes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
