実行（execution）とジョブの違いは何ですか？

実行は、ワークフロー全体を 1 回実行したものです。すべてのノードの状態を記録し、その実行で作成されたジョブを、AI ノードごとに 1 つずつまとめます。ジョブは、1 枚の画像や 1 本の動画のレンダリングなど、1 回の生成です。

ワークフローの実行のステータスは、どうすれば取得できますか？

GET /v1/workflow-executions/:id を 2〜5 秒ごとにポーリングします。実行のステータス、完了したノードと失敗したノードの数、それまでに使ったクレジット、すべてのノードの状態が返ります。ステータスが completed、failed、cancelled、timed_out、discarded のいずれかになったら、ポーリングを止めます。

ワークフローの実行は、どうすればキャンセルできますか？

POST /v1/workflow-executions/:id/cancel を送ります。mode を指定しない場合はすぐにキャンセルされ、確保されたクレジットは返還されます。mode に after_current を指定すると、実行中のノードが先に完了します。mode に discard を指定すると、実行中のジョブは完了しますが、新しいノードは開始されません。

実行の中で、ノードの結果はどこにありますか？

nodeStates の中の、そのノードの ID の下にあります。完了したノードは、結果を output に持っています。たとえば、output.imageUrl、output.videoUrl、output.audioUrl、output.text です。

ワークフローの過去の実行を一覧表示できますか？

はい。GET /v1/workflows/:id/executions は、ワークフローの実行をページ単位で返します。ステータスや、実行を開始した場所で絞り込むこともできます。

Nodaro API の実行（execution）：ワークフロー実行のステータス、履歴、キャンセル

Nodaro のワークフローの実行をノードごとに追跡し、各ノードの結果を読み取ります。過去の実行を一覧表示し、実行をすぐに、または実行中のノードの完了後にキャンセルします。

実行（execution）は、ワークフロー全体を 1 回実行したものです。実行には、そのステータス、完了したノードの数、使用したクレジット、すべてのノードの状態と結果が記録されます。また、その実行で作成されたジョブも、AI ノードごとに 1 つずつまとめられます。POST /v1/workflows/:id/run は executionId を返し、実行のエンドポイントで、その実行を最後まで追跡できます。

エンドポイント

メソッド	パス	説明
`GET`	`/v1/workflow-executions/:id`	1 件の実行について、ステータス、ノード数、クレジット、すべてのノードの状態を返します。
`GET`	`/v1/workflow-executions/:id/stream`	同じ実行を、Server-Sent Events のストリームとして返します。
`GET`	`/v1/workflows/:id/executions`	1 つのワークフローの実行を、ページ単位で返します。
`POST`	`/v1/workflow-executions/:id/cancel`	実行を、すぐに、または実行中のノードの完了後にキャンセルします。
`GET`	`/v1/api/status/:execId`	API トークン用のルートです。実行のステータス、ノード数、使用したクレジットを返します。
`GET`	`/v1/api/result/:execId`	API トークン用のルートです。完了した実行の出力を返します。

最後の 2 つは、POST /v1/api/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
  }
}

フィールド	意味
`status`	実行のステータスです。下の表を参照してください。
`triggerType`	実行を開始したものです。`manual`、`webhook`、`schedule`、`app_run`、`single-node` などがあります。
`totalNodes`、`completedNodes`、`failedNodes`	ノード数です。進行状況は `completedNodes / totalNodes` で表示します。
`totalCreditsUsed`	その実行がこれまでに使ったクレジットです。
`errorMessage`	実行が失敗または停止した理由を、文章で示します。
`nodeStates`	すべてのノードの状態で、ノード ID をキーとしています。
`completedAt`	実行が終了した日時、または `null` です。

単独で実行した 1 つのノードのジョブの ID も、ここで使えます。その場合、サーバーは同じ形式で、その 1 つのノードについての情報を返します。存在しない ID や、自分のものではない ID には、404 が返ります。

実行のステータス

ステータス	最終状態	意味
`pending`	いいえ	実行はキューで待機しています。
`running`	いいえ	ノードを実行しています。
`stopping`	いいえ	`after_current` でキャンセルしました。実行中のノードが完了した後、実行が停止します。
`completed`	はい	実行が完了しました。
`failed`	はい	実行が失敗しました。理由は `errorMessage` に示されます。
`cancelled`	はい	実行がキャンセルされました。
`timed_out`	はい	実行がタイムアウトしました。
`discarded`	はい	`discard` でキャンセルしました。実行中だったジョブは完了しましたが、キャンバスは更新されていません。

ノードの状態

nodeStates の各エントリーには status があり、値は pending、running、completed、failed、skipped のいずれかです。失敗したノードには、error も含まれます。

完了したノードは、結果を output に持っています。キーはノードの出力によって異なります。url、imageUrl、videoUrl、audioUrl、resultUrl、text の順に探してください。

実行が構造化された結果を保持した場合は、失敗したノードにも output が含まれることがあります。現在これに当てはまるのは、3D シーンを作成するノードです。すべての修正を試してもビジュアルレビューに通らなかったシーンでも、下書きは出力されます。その場合、ノードは、その下書きを output.plan に入れた状態で失敗します。ここから、次の 2 つのルールが導かれます。

ステータスではなく、フィールドの有無を確認します。pending や running のノードに output があることはありません。また、今後はほかの種類のノードも結果を保持する可能性があります。
output があることは、成功を意味しません。ノードは失敗しており、何かを保持しているだけです。

SDK は、completed と failed で true を返す nodeStateMayCarryOutput(status) と、同じ 2 つのステータスをまとめた OUTPUT_BEARING_NODE_STATUSES をエクスポートしています。

実行の終了を待つ

ステータスが最終状態になるまで、2〜5 秒ごとにポーリングします。

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

--watch を付けると、CLI は実行が終わるまでポーリングし、成功した場合はコード 0、実行が失敗した場合は 2、キャンセルされた場合は 130 で終了します。--json を付けると、ペイロードを出力して正常終了するので、.status を自分で確認してください。

GET /v1/workflow-executions/:id/stream は、実行中、同じ実行の状態を Server-Sent Events として送ります。ノードの output のルールも、上記の読み取りと同じです。ほとんどの連携では、ポーリングのほうが簡単です。

ワークフローの実行の一覧

GET /v1/workflows/:id/executions は、ワークフローの実行を { data, nextCursor } の形式で、ページ単位で返します。この一覧には、ワークフロー全体の実行に加えて、そのワークフローで単独で実行したノードのジョブも含まれます。

クエリパラメーター	意味
`limit`	ページのサイズです。
`cursor`	前のページの `nextCursor` です。
`status`	カンマ区切りのステータスです。たとえば `pending,running` のように指定します。
`source`	`editor` は、アプリ、Webhook、スケジュールで開始した実行を除外します。`all` は、それらも含めます。

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',
})

実行のキャンセル

POST /v1/workflow-executions/:id/cancel は、実行を停止します。リクエストボディの任意の mode で、すでに実行中のノードの扱いが決まります。

`mode`	動作	最終ステータス
なし	実行はすぐに停止します。実行中のジョブはキャンセルされ、確保されていたクレジットは返還されます。	`cancelled`
`after_current`	実行中のノードは完了し、その結果はキャンバスとライブラリに保存されます。その後、実行が停止します。	`stopping` の後、最終ステータス
`discard`	新しいノードは開始されません。実行中のジョブはモデル側で止められないため、完了してライブラリに保存されますが、結果はキャンバスに書き込まれません。それらのジョブは完了しているため、返還はありません。	`discarded`

レスポンスは { "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

実行全体ではなく 1 つの生成だけを止めるには、そのジョブをキャンセルします。ジョブを参照してください。

実行とジョブ

実行の AI ノードは、それぞれジョブを 1 つ作成し、ジョブが終わると、そのノードの結果が nodeStates に入ります。実行全体を追跡するには、実行を読み取ります。1 回の生成の詳細を確認するには、ジョブを読み取ります。ジョブからは、error_hint、credit_status、そして input_data に記録された、モデルに送られた内容のすべてがわかります。

Webhook トリガー（Webhook Trigger）の呼び出しやスケジュールトリガー（Schedule Trigger）の起動など、トリガーが開始した実行も実行であり、triggerType は webhook または schedule になります。Webhook を参照してください。

実行