Executions

An execution is one run of a whole workflow. It records the run's status, how many nodes have finished, the credits used, and the state and result of every node, and it groups the jobs the run created, one for each AI node. POST /v1/workflows/:id/run returns an executionId, and the execution endpoints follow that run to its end.

Endpoints

The last two belong to the runs started with POST /v1/api/run. They are described in Run a workflow with new input values.

Get a run

curl -s https://app.nodaro.ai/v1/workflow-executions/3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $NODARO_API_KEY"

const { data } = await client.executions.get(executionId)
console.log(data.status, `${data.completedNodes}/${data.totalNodes}`)

nodaro executions get 3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b --json

{
  "data": {
    "id": "3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b",
    "workflowId": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
    "status": "running",
    "triggerType": "manual",
    "totalNodes": 4,
    "completedNodes": 2,
    "failedNodes": 0,
    "totalCreditsUsed": 45,
    "errorMessage": null,
    "nodeStates": {
      "text-prompt-1": { "status": "completed", "output": { "text": "a knight on a hill at dawn" } },
      "generate-image-1": { "status": "completed", "output": { "imageUrl": "https://…/knight.png" } },
      "generate-video-1": { "status": "running" },
      "add-captions-1": { "status": "pending" }
    },
    "completedAt": null
  }
}

The id of a standalone single-node job also works here: the server answers with the same shape, describing that one node. An id that does not exist or is not yours answers 404.

Run statuses

Node states

Each entry in nodeStates has a status: pending, running, completed, failed or skipped. A failed node also carries its error, and errorDetail when the provider gave a reason in its own words. A node that fails inside a sub-workflow hands those words to the sub-workflow node's entry. The words can quote the workflow's prompt, so errorDetail reaches only a caller who can open the workflow that the run executed, that is its creator or someone it is shared with. A published app's runner never receives it. Neither does a person who runs someone else's share link, on the share link's run status (GET /v1/present/:token/status/:execId) or on the run reads. A run that executes no saved workflow, such as the hidden run of a use-case node, carries the words to its owner. A deployment can also keep the words for its administrators with the surface profile key jobs.errorDetail. See The provider's own words. A node skipped because its input carried nothing in this run reads { "status": "skipped", "skipReason": "empty_input" }. A node skipped by a Router's inactive route carries no skipReason. See Runs that find nothing new.

A completed node carries its result in output. The keys depend on the node's output: look for url, imageUrl, videoUrl, audioUrl, resultUrl or text, in that order.

A failed node can carry output too, when the run kept a structured result. The 3D scene authoring nodes are the case today: a scene whose visual review failed after every repair still published a draft, and the node fails with that draft in output.plan. Two rules follow:

• Check for the field, not the status. A pending or running node never has output, and other node types may keep results in future.
• A present output is not success. The node failed; it only kept something.

The SDK exports nodeStateMayCarryOutput(status), which is true for completed and failed, and the same pair as OUTPUT_BEARING_NODE_STATUSES.

Wait for a run to end

Poll every 2 to 5 seconds until the status is final:

const { executionId } = await client.workflows.run(workflowId)

const final = ['completed', 'failed', 'cancelled', 'timed_out', 'discarded']
while (true) {
  const { data } = await client.executions.get(executionId)
  console.log(`${data.completedNodes}/${data.totalNodes} nodes done`)
  if (final.includes(data.status)) {
    if (data.status !== 'completed') throw new Error(`Run ${data.status}: ${data.errorMessage ?? 'no message'}`)
    console.log(`Done. Used ${data.totalCreditsUsed} credits.`)
    break
  }
  await new Promise((r) => setTimeout(r, 2_000))
}

while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $NODARO_API_KEY" \
    "https://app.nodaro.ai/v1/workflow-executions/$EXEC" | jq -r .data.status)
  echo "Status: $STATUS"
  case "$STATUS" in completed|failed|cancelled|timed_out|discarded) break;; esac
  sleep 3
done

nodaro executions get 3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b --watch

With --watch, the CLI polls until the run ends and exits with code 0 on success, 2 when the run failed and 130 when it was cancelled. With --json, it prints the payload and exits normally, so check .status yourself.

GET /v1/workflow-executions/:id/stream sends the same run state as server-sent events while the run is in progress, and it carries the same node output rules as the read above. Polling is the simpler choice for most integrations.

List a workflow's runs

GET /v1/workflows/:id/executions returns a workflow's runs in pages, as { data, nextCursor }. The list includes the standalone single-node jobs of that workflow beside its full runs.

curl -s "https://app.nodaro.ai/v1/workflows/$WORKFLOW_ID/executions?limit=20&status=completed" \
  -H "Authorization: Bearer $NODARO_API_KEY"

const { data, nextCursor } = await client.executions.listForWorkflow(workflowId, {
  limit: 20,
  status: 'completed',
})

Cancel a run

POST /v1/workflow-executions/:id/cancel stops a run. The optional mode in the body decides what happens to the nodes already running:

The answer is { "success": true }.

curl -s -X POST https://app.nodaro.ai/v1/workflow-executions/$EXEC/cancel \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "after_current"}'

await client.executions.cancel(executionId)                           // now
await client.executions.cancel(executionId, { mode: 'after_current' }) // after running nodes
await client.executions.cancel(executionId, { mode: 'discard' })       // stop scheduling

nodaro executions cancel 3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b                # now
nodaro executions cancel 3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b --mode stopping # after running nodes

To stop one generation instead of a whole run, cancel its job: see Jobs.

Executions and jobs

A run's AI nodes each create a job, and nodeStates carries each node's result once its job is done. Read the execution to follow the run as a whole. Read a job for the details of one generation: its error_hint, its credit_status, or everything that was sent to the model in input_data.

Runs that a trigger starts, such as a Webhook Trigger call or a Schedule Trigger firing, are executions too, with triggerType webhook or schedule. See Webhooks.