Execuções

Uma execução é cada vez que um workflow inteiro é executado. Ela registra o status da execução, quantos nós já terminaram, os créditos usados e o estado e o resultado de cada nó. Ela também agrupa os jobs que a execução criou, um para cada nó de IA. POST /v1/workflows/:id/run retorna um executionId, e os endpoints de execuções acompanham essa execução até o fim.

Endpoints

As duas últimas pertencem às execuções iniciadas com POST /v1/api/run. Elas estão descritas em Executar um workflow com novos valores de entrada.

Obter uma execução

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
  }
}

O ID de um job avulso de um único nó também funciona aqui: o servidor responde com o mesmo formato, descrevendo esse nó. Um ID que não existe ou não é seu responde 404.

Status das execuções

Estados dos nós

Cada entrada de nodeStates tem um status: pending, running, completed, failed ou skipped. Um nó com falha também traz o error dele.

Um nó concluído traz o resultado em output. As chaves dependem da saída do nó: procure url, imageUrl, videoUrl, audioUrl, resultUrl ou text, nessa ordem.

Um nó com falha também pode trazer output, quando a execução guardou um resultado estruturado. Hoje, esse é o caso dos nós de criação de cenas 3D. Uma cena cuja revisão visual falhou depois de todas as correções ainda publicou um rascunho, e o nó falha com esse rascunho em output.plan. Daí vêm duas regras:

• Verifique o campo, não o status. Um nó em pending ou running nunca tem output, e outros tipos de nó podem guardar resultados no futuro.
• Um output presente não é sucesso. O nó falhou; ele só guardou alguma coisa.

O SDK exporta nodeStateMayCarryOutput(status), que é true para completed e failed, e o mesmo par como OUTPUT_BEARING_NODE_STATUSES.

Esperar uma execução terminar

Consulte periodicamente, a cada 2 a 5 segundos, até o status ser 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

Com --watch, a CLI consulta periodicamente até a execução terminar e sai com o código 0 em caso de sucesso, 2 quando a execução falhou e 130 quando ela foi cancelada. Com --json, ela imprime o payload e sai normalmente, então verifique .status você mesmo.

GET /v1/workflow-executions/:id/stream envia o mesmo estado da execução como server-sent events enquanto a execução está em andamento, com as mesmas regras de output dos nós da leitura acima. A consulta periódica é a opção mais simples para a maioria das integrações.

Listar as execuções de um workflow

GET /v1/workflows/:id/executions retorna as execuções de um workflow em páginas, como { data, nextCursor }. A lista inclui os jobs avulsos de um único nó desse workflow ao lado das execuções completas.

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

Cancelar uma execução

POST /v1/workflow-executions/:id/cancel interrompe uma execução. O mode opcional no corpo decide o que acontece com os nós que já estão em execução:

A resposta é { "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

Para interromper uma geração em vez de uma execução inteira, cancele o job dela: veja Jobs.

Execuções e jobs

Cada nó de IA de uma execução cria um job, e nodeStates traz o resultado de cada nó assim que o job dele termina. Leia a execução para acompanhar o andamento geral. Leia um job para ver os detalhes de uma geração: o error_hint, o credit_status ou tudo o que foi enviado ao modelo em input_data.

Quando um gatilho inicia o workflow, como uma chamada a um Gatilho de webhook (Webhook Trigger) ou o disparo de um Gatilho agendado (Schedule Trigger), isso também gera uma execução, com triggerType webhook ou schedule. Veja Webhooks.