Workflows

Workflows & Executions

NocoDB Workflows is the platform's built-in automation engine — a node-graph editor inside the NocoDB UI. The Meta API v3 surface for Workflows is read + execute only: you can list workflows, fetch their definitions, run them on demand, list executions, and read execution details. Workflow authoring (creating / editing the node graph) lives in the NocoDB UI; this API does not expose it.

If you need to create automations programmatically, integrate with an external orchestrator (n8n, Trigger.dev) instead — see the related plugins. NocoDB Workflows is a no-code in-UI tool.

Endpoints

List Workflows

curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/workflows"

Returns a WorkflowList — array of { id, title, description, status, created_at, updated_at }.

Get Workflow Definition

curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/workflows/$WORKFLOW_ID"

Returns a WorkflowGetResponse containing:

• nodes — array of WorkflowNode (each node has type, position, config, ports)
• edges — array of WorkflowEdge (source/target node IDs)
• variables — array of WorkflowVariableDefinition (input variables the workflow expects)
• options — WorkflowOptions

Probe the spec for the full graph shape:

jq '.components.schemas.WorkflowGetResponse' \
   skills/api-reference/references/nocodb-meta-openapi.json

Execute a Workflow

curl -sS -X POST \
  -H "xc-token: $NOCODB_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input":   { "customer_id": "rec_abc123", "amount": 1500 },
    "trigger": "manual"
  }' \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/workflows/$WORKFLOW_ID/execute"

input keys must match the workflow's WorkflowVariableDefinition names. The response returns the new execution_id — poll /executions/{execution_id} to get the result, or stream the dashboard.

List Recent Executions

curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/workflows/$WORKFLOW_ID/executions"

Returns a WorkflowExecutionList — array of { id, status, started_at, finished_at, trigger, error? }. Status values: pending, running, succeeded, failed, cancelled.

Inspect One Execution

curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/workflows/$WORKFLOW_ID/executions/$EXECUTION_ID"

Returns a WorkflowExecutionGetResponse with:

• Top-level: id, status, started_at, finished_at, trigger, input, output, error
• node_results — array of WorkflowNodeExecutionResult (status, input, output, error per node)
• loop_data — WorkflowLoopData for loop nodes

This is your debugging surface: when a workflow fails, the per-node error tells you which node broke.

Common Patterns

Trigger on a record event

A workflow can be wired in the NocoDB UI to a Hook event. Programmatically you'd:

1. Create the workflow in NocoDB UI (graph + variables).
2. Configure a hook with notification.type: "Script" whose script calls the /execute endpoint with the triggering record's data — see the webhooks and api-reference skills.

Poll until done

EXEC_ID=$(curl -sS -X POST -H "xc-token: $NOCODB_API_TOKEN" \
  -d '{"trigger":"manual"}' \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/workflows/$WORKFLOW_ID/execute" | jq -r '.id')

while :; do
  STATUS=$(curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
    "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/workflows/$WORKFLOW_ID/executions/$EXEC_ID" | jq -r '.status')
  case "$STATUS" in
    succeeded|failed|cancelled) echo "Done: $STATUS"; break ;;
    *) sleep 2 ;;
  esac
done

List failures from the last hour

curl -sS -H "xc-token: $NOCODB_API_TOKEN" \
  "$NOCODB_URL/api/v3/meta/bases/$BASE_ID/workflows/$WORKFLOW_ID/executions" \
  | jq '[ .executions[] | select(.status=="failed") | select(.started_at > (now - 3600 | strftime("%Y-%m-%dT%H:%M:%SZ"))) ]'

Troubleshooting

What This Skill Does NOT Cover

• Authoring workflows (creating nodes, connecting edges) — done in the NocoDB UI.
• Workflow templates or marketplace integration.
• Cross-platform automation (use n8n / Trigger.dev for that, with workflows reaching out via HTTP).

See Also

• api-reference skill — full Meta API v3 reference
• references/nocodb-meta-openapi.json — OpenAPI source for all Workflow* schemas
• webhooks skill — for event-driven triggers that can launch workflows via Script notifications