NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
API REST

Execuções

Acompanhe uma execução de workflow nó a nó, leia o resultado de cada nó, liste execuções passadas e cancele agora ou quando os nós em andamento terminarem.

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 as tarefas que a execução criou, uma 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

MétodoCaminhoO que faz
GET/v1/workflow-executions/:idUma execução: status, contagens de nós, créditos e o estado de cada nó.
GET/v1/workflow-executions/:id/streamA mesma execução como um fluxo de server-sent events.
GET/v1/workflows/:id/executionsAs execuções de um workflow, em páginas.
POST/v1/workflow-executions/:id/cancelCancela uma execução, agora ou depois que os nós em andamento terminarem.
GET/v1/api/status/:execIdA via dos tokens de API: status, contagens de nós e créditos usados de uma execução.
GET/v1/api/result/:execIdA via dos tokens de API: as saídas de uma execução terminada.

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
  }
}
CampoSignificado
statusO status da execução. Veja a tabela abaixo.
triggerTypeO que iniciou a execução, como manual, webhook, schedule, app_run ou single-node.
totalNodes, completedNodes, failedNodesContagens de nós. Mostre o progresso como completedNodes / totalNodes.
totalCreditsUsedOs créditos usados pela execução até agora. Inclui as etapas já liquidadas da tarefa de cada nó, também as de um nó que falhou. Uma etapa liquidada depois do fim do seu nó é contada quando a execução termina.
errorMessagePor que a execução falhou ou parou, em palavras.
nodeStatesO estado de cada nó, indexado pelo ID do nó.
completedAtQuando a execução terminou, ou null.

O ID de uma tarefa avulsa 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

StatusFinalSignificado
pendingNãoA execução está na fila.
runningNãoOs nós estão em execução.
stoppingNãoVocê cancelou com after_current: os nós em andamento terminam e, depois, a execução para.
completedSimA execução terminou.
failedSimA execução falhou. errorMessage diz por quê.
cancelledSimA execução foi cancelada.
timed_outSimO tempo da execução se esgotou.
discardedSimVocê cancelou com discard: as tarefas em andamento terminaram sem atualizar o canvas.

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, e errorDetail quando o provedor deu um motivo com as próprias palavras. Um nó que falha dentro de um sub-workflow passa essas palavras para a entrada do nó de sub-workflow. As palavras podem citar o prompt do workflow, então errorDetail só chega a quem pode abrir o workflow que a execução rodou, ou seja, o criador dele ou alguém com quem ele foi compartilhado. Quem executa um app publicado nunca o recebe. Nem quem executa o link de compartilhamento de outra pessoa, no status de execução do link (GET /v1/present/:token/status/:execId) ou nas leituras da execução. Uma execução que não roda nenhum workflow salvo, como a execução oculta de um nó de caso de uso, leva as palavras ao dono dela. Uma implantação também pode reservar as palavras aos administradores dela com a chave de perfil de superfície jobs.errorDetail. Veja As palavras do próprio provedor. Um nó pulado porque a entrada dele não trouxe nada nesta execução mostra { "status": "skipped", "skipReason": "empty_input" }. Um nó pulado pela rota inativa de um Roteador não traz skipReason. Veja Execuções que não encontram nada novo.

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 as tarefas avulsas de um único nó desse workflow ao lado das execuções completas.

Parâmetro de consultaSignificado
limitO tamanho da página.
cursorO nextCursor da página anterior.
statusStatus separados por vírgula, por exemplo pending,running.
sourceeditor deixa de fora as execuções iniciadas por apps, webhooks e agendamentos. all inclui essas execuções.
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:

modeO que aconteceStatus final
nenhumA execução para agora. As tarefas em andamento são canceladas, e os créditos reservados para elas são reembolsados.cancelled
after_currentOs nós em andamento terminam, e os resultados deles vão para o canvas e para a sua biblioteca. Depois, a execução para.stopping e, depois, o status final
discardNenhum nó novo é iniciado. As tarefas em andamento não podem ser interrompidas no modelo, então elas terminam e são salvas na sua biblioteca, mas os resultados não são gravados no canvas. Não há reembolso, porque essas tarefas foram concluídas.discarded

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 a tarefa dela: veja Tarefas.

Execuções e tarefas

Cada nó de IA de uma execução cria uma tarefa, e nodeStates traz o resultado de cada nó assim que a tarefa dele termina. Leia a execução para acompanhar o andamento geral. Leia uma tarefa 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 ou o disparo de um Gatilho agendado, isso também gera uma execução, com triggerType webhook ou schedule. Veja Webhooks.

Perguntas frequentes

Qual é a diferença entre uma execução e uma tarefa?

Uma execução é cada vez que um workflow inteiro é executado. Ela registra o estado de cada nó e agrupa as tarefas que criou, uma para cada nó de IA. Uma tarefa é uma única geração, como uma imagem ou uma renderização de vídeo.

Como obtenho o status de uma execução de workflow?

Consulte periodicamente GET /v1/workflow-executions/:id, a cada 2 a 5 segundos. A rota retorna o status da execução, quantos nós terminaram e falharam, os créditos usados até agora e o estado de cada nó. Pare quando o status for completed, failed, cancelled, timed_out ou discarded.

Como cancelo uma execução de workflow?

Envie POST /v1/workflow-executions/:id/cancel. Sem um modo, a rota cancela na hora e reembolsa os créditos reservados. Com o modo after_current, os nós em andamento terminam primeiro. Com o modo discard, as tarefas em andamento terminam, mas nenhum nó novo é iniciado.

Onde fica o resultado de um nó em uma execução?

Em nodeStates, sob o ID do nó. Um nó concluído traz o resultado em output, por exemplo output.imageUrl, output.videoUrl, output.audioUrl ou output.text.

Posso listar as execuções anteriores de um workflow?

Sim. GET /v1/workflows/:id/executions retorna as execuções do workflow em páginas, e você pode filtrá-las por status e pelo lugar de onde foram iniciadas.

Última atualização

Nesta página