# 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.

Source: https://nodaro.ai/pt-BR/docs/developers/api/executions

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
| Método | Caminho | O que faz |
| --- | --- | --- |
| `GET` | `/v1/workflow-executions/:id` | Uma execução: status, contagens de nós, créditos e o estado de cada nó. |
| `GET` | `/v1/workflow-executions/:id/stream` | A mesma execução como um fluxo de server-sent events. |
| `GET` | `/v1/workflows/:id/executions` | As execuções de um workflow, em páginas. |
| `POST` | `/v1/workflow-executions/:id/cancel` | Cancela uma execução, agora ou depois que os nós em andamento terminarem. |
| `GET` | `/v1/api/status/:execId` | A via dos tokens de API: status, contagens de nós e créditos usados de uma execução. |
| `GET` | `/v1/api/result/:execId` | A 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](https://nodaro.ai/docs/developers/api/workflows#run-a-workflow-with-new-input-values).

## Obter uma execução
**curl**

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

**TypeScript SDK**

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

**CLI**

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

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

| Campo | Significado |
| --- | --- |
| `status` | O status da execução. Veja a tabela abaixo. |
| `triggerType` | O que iniciou a execução, como `manual`, `webhook`, `schedule`, `app_run` ou `single-node`. |
| `totalNodes`, `completedNodes`, `failedNodes` | Contagens de nós. Mostre o progresso como `completedNodes / totalNodes`. |
| `totalCreditsUsed` | Os créditos usados pela execução até agora. |
| `errorMessage` | Por que a execução falhou ou parou, em palavras. |
| `nodeStates` | O estado de cada nó, indexado pelo ID do nó. |
| `completedAt` | Quando a execução terminou, ou `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
| Status | Final | Significado |
| --- | --- | --- |
| `pending` | Não | A execução está na fila. |
| `running` | Não | Os nós estão em execução. |
| `stopping` | Não | Você cancelou com `after_current`: os nós em andamento terminam e, depois, a execução para. |
| `completed` | Sim | A execução terminou. |
| `failed` | Sim | A execução falhou. `errorMessage` diz por quê. |
| `cancelled` | Sim | A execução foi cancelada. |
| `timed_out` | Sim | O tempo da execução se esgotou. |
| `discarded` | Sim | Você cancelou com `discard`: os jobs 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.

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:

**TypeScript SDK**

```ts
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))
}
```

**curl**

```bash
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
```

**CLI**

```bash
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.

| Parâmetro de consulta | Significado |
| --- | --- |
| `limit` | O tamanho da página. |
| `cursor` | O `nextCursor` da página anterior. |
| `status` | Status separados por vírgula, por exemplo `pending,running`. |
| `source` | `editor` deixa de fora as execuções iniciadas por apps, webhooks e agendamentos. `all` inclui essas execuções. |

**curl**

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

**TypeScript SDK**

```ts
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:

| `mode` | O que acontece | Status final |
| --- | --- | --- |
| nenhum | A execução para agora. Os jobs em andamento são cancelados, e os créditos reservados para eles são reembolsados. | `cancelled` |
| `after_current` | Os 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 |
| `discard` | Nenhum nó novo é iniciado. Os jobs em andamento não podem ser interrompidos no modelo, então eles terminam e são salvos na sua biblioteca, mas os resultados não são gravados no canvas. Não há reembolso, porque esses jobs foram concluídos. | `discarded` |

A resposta é `{ "success": true }`.

**curl**

```bash
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"}'
```

**TypeScript SDK**

```ts
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
```

**CLI**

```bash
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](https://nodaro.ai/docs/developers/api/jobs#cancel-or-delete-a-job).

## Execuções e jobs
Cada nó de IA de uma execução cria um [job](https://nodaro.ai/docs/developers/api/jobs), 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)](https://nodaro.ai/docs/nodes/automate/webhook-trigger) ou o disparo de um [**Gatilho agendado** (Schedule Trigger)](https://nodaro.ai/docs/nodes/automate/schedule-trigger), isso também gera uma execução, com `triggerType` `webhook` ou `schedule`. Veja [Webhooks](https://nodaro.ai/docs/developers/api/webhooks).

## Frequently asked questions

### Qual é a diferença entre uma execução e um job?

Uma execução é cada vez que um workflow inteiro é executado. Ela registra o estado de cada nó e agrupa os jobs que criou, um para cada nó de IA. Um job é 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, os jobs 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.