Nodaro API 실행: 워크플로 실행 상태, 기록, 취소

Nodaro 워크플로 실행을 노드별로 추적하고, 각 노드의 결과를 읽고, 지난 실행 목록을 보며, 실행을 바로 또는 실행 중인 노드가 끝난 뒤 취소합니다.

실행은 워크플로 전체를 한 번 실행한 기록입니다. 실행에는 상태, 완료된 노드 수, 사용한 크레딧, 모든 노드의 상태와 결과가 기록되며, 실행이 만든 작업이 AI 노드마다 하나씩 묶입니다. POST /v1/workflows/:id/run은 executionId를 반환하고, 실행 엔드포인트로 그 실행을 끝까지 추적합니다.

엔드포인트

메서드	경로	설명
`GET`	`/v1/workflow-executions/:id`	실행 하나의 상태, 노드 수, 크레딧, 모든 노드의 상태를 가져옵니다.
`GET`	`/v1/workflow-executions/:id/stream`	같은 실행을 서버 전송 이벤트 스트림으로 받습니다.
`GET`	`/v1/workflows/:id/executions`	한 워크플로의 실행을 페이지 단위로 가져옵니다.
`POST`	`/v1/workflow-executions/:id/cancel`	실행을 바로, 또는 실행 중인 노드가 끝난 뒤 취소합니다.
`GET`	`/v1/api/status/:execId`	API 토큰 경로입니다. 실행의 상태, 노드 수, 사용한 크레딧을 가져옵니다.
`GET`	`/v1/api/result/:execId`	API 토큰 경로입니다. 끝난 실행의 출력을 가져옵니다.

마지막 두 라우트는 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`입니다.

독립 단일 노드 작업의 id도 여기서 쓸 수 있습니다. 서버는 같은 형태로, 그 노드 하나를 설명하는 응답을 반환합니다. 존재하지 않거나 내 것이 아닌 id는 404를 반환합니다.

실행 상태

상태	최종	의미
`pending`	아니요	실행이 대기열에 있습니다.
`running`	아니요	노드가 실행 중입니다.
`stopping`	아니요	`after_current`로 취소했습니다. 실행 중인 노드가 끝나면 실행이 멈춥니다.
`completed`	예	실행이 끝났습니다.
`failed`	예	실행이 실패했습니다. `errorMessage`에 이유가 있습니다.
`cancelled`	예	실행이 취소되었습니다.
`timed_out`	예	실행 시간이 초과되었습니다.
`discarded`	예	`discard`로 취소했습니다. 실행 중인 작업이 캔버스를 업데이트하지 않고 끝났습니다.

nodeStates의 각 항목에는 status가 있으며, 값은 pending, running, completed, failed, skipped 중 하나입니다. 실패한 노드에는 error도 있습니다. 이번 실행에서 입력이 아무것도 전달하지 않아 건너뛴 노드는 { "status": "skipped", "skipReason": "empty_input" }입니다. 라우터의 비활성 경로 때문에 건너뛴 노드에는 skipReason이 없습니다. 새 내용이 없는 실행을 참고하세요.

완료된 노드는 output에 결과를 담습니다. 키는 노드의 출력에 따라 다릅니다. url, imageUrl, videoUrl, audioUrl, resultUrl, text 순서로 찾으세요.

실패한 노드에도, 실행이 구조화된 결과를 남긴 경우에는 output이 있을 수 있습니다. 현재는 3D 장면 작성 노드가 이에 해당합니다. 모든 수정을 거친 뒤에도 시각 검토를 통과하지 못한 장면도 초안은 게시하며, 노드는 그 초안을 output.plan에 담은 채 실패합니다. 여기서 두 가지 규칙이 나옵니다.

상태가 아니라 필드를 확인하세요. pending이나 running 노드에는 output이 없으며, 앞으로 다른 노드 유형도 결과를 남길 수 있습니다.
output이 있다고 성공한 것은 아닙니다. 노드는 실패했고, 무언가를 남겼을 뿐입니다.

SDK는 completed와 failed에서 true인 nodeStateMayCarryOutput(status)를 내보내며, 같은 두 값을 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은 실행이 진행되는 동안 같은 실행 상태를 서버 전송 이벤트로 보내며, 위의 읽기와 같은 노드 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

전체 실행 대신 생성 하나만 멈추려면 해당 작업을 취소하세요. 작업을 참조하세요.

실행과 작업

실행의 AI 노드는 각각 작업을 하나씩 만들며, 작업이 끝나면 nodeStates에 각 노드의 결과가 담깁니다. 실행 전체를 추적하려면 실행을 읽으세요. 생성 하나의 세부 정보, 즉 error_hint, credit_status, 또는 모델에 보낸 모든 내용이 담긴 input_data를 보려면 작업을 읽으세요.

Webhook 트리거 호출이나 일정 트리거 발동처럼 트리거가 시작한 실행도 실행이며, triggerType은 webhook 또는 schedule입니다. Webhook을 참조하세요.

자주 묻는 질문

실행과 작업은 어떻게 다른가요?

실행은 워크플로 전체를 한 번 실행한 기록입니다. 모든 노드의 상태를 기록하고, 실행이 만든 작업을 AI 노드마다 하나씩 묶습니다. 작업은 이미지 한 장이나 동영상 렌더링 한 번 같은 단일 생성입니다.

워크플로 실행의 상태를 확인하려면 어떻게 하나요?

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는 워크플로의 실행을 페이지 단위로 반환하며, 상태와 실행을 시작한 곳으로 필터링할 수 있습니다.

실행

엔드포인트

실행 가져오기

실행 상태

노드 상태

실행이 끝날 때까지 대기

워크플로의 실행 목록

실행 취소

실행과 작업

자주 묻는 질문

워크플로

작업

Webhook

워크플로 실행

오류

목차

실행

자주 묻는 질문

관련 문서

워크플로

작업

Webhook

워크플로 실행

오류

목차