> ## Documentation Index
> Fetch the complete documentation index at: https://magica.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Runs & Execution

> How workflow runs work over MCP — request nodes, result shape, smart routing, and polling.

Workflow runs are asynchronous. Start one with `start_run`, then poll `get_run_status` for status until it reaches a terminal state.

***

## Request Node Handling

When a workflow contains a **Request Node** with input fields, `start_run` automatically detects it and guides the AI assistant through providing values.

<Steps>
  <Step title="Initial call">
    The AI assistant calls `start_run` with just the `workflowId`.
  </Step>

  <Step title="Field discovery">
    The tool detects Request Node fields and returns their names, types, and
    current defaults — **instead of** starting the run.
  </Step>

  <Step title="Call with values">
    The AI assistant calls `start_run` again with the `values` parameter filled
    in for each Request Node field.
  </Step>

  <Step title="Run executes">
    The workflow runs with the provided inputs. Values are synced to the Request
    Node in the UI.
  </Step>
</Steps>

<Info>
  The `values` parameter is keyed by `nodeId` then `fieldId`. The tool returns
  the exact field IDs needed, so the AI assistant can construct the correct
  payload automatically.
</Info>

***

## Run Results

Both `start_run` and `get_run_status` return a structured response with two sections:

<Tabs>
  <Tab title="Response Output">
    The **Response Node** output — the final workflow result. This is always
    listed first in the response so the AI assistant can surface the primary
    result immediately.
  </Tab>

  <Tab title="Node Outputs">
    Status and output of **every node** in the workflow. Response nodes appear
    first, followed by all other nodes. Each entry includes the node type, ID,
    status, and output (or error).
  </Tab>
</Tabs>

<Note>
  If the workflow is still running, the response shows the current execution
  state and per-node statuses instead. Use `get_run_status` to poll for the
  final result.
</Note>

***

## Choosing the Right Tool

The MCP server has two execution paths depending on what you're doing:

| User intent                         | Tool           | Notes                                           |
| ----------------------------------- | -------------- | ----------------------------------------------- |
| "Generate an image of a Ferrari"    | `execute_tool` | One-shot generation — no workflow needed        |
| "Run my saved workflow My Pipeline" | `start_run`    | User workflows → falls back to system templates |
| "Run the Nano Banana Pro template"  | `start_run`    | Workflow name fuzzy-matches system templates    |

Workflow name lookups in `start_run` use **fuzzy matching** — partial names like "Nano Banana" match "Nano Banana Pro".

<Tip>
  For single-step generation (one image / one video / one TTS clip), prefer
  `execute_tool` over building a workflow. Workflows are for reusable multi-step
  pipelines the user explicitly wants to save.
</Tip>

***

## Checking Run Status

After starting a run, use `get_run_status` to check progress. The same tool works for both `execute_tool` and `start_run` results:

```
execute_tool / start_run  →  returns runId + initial status
get_run_status(runId)     →  long-polls until COMPLETED / FAILED / CANCELED
```

`get_run_status` long-polls (\~12 min window) and returns either the final result or a `still-running` response telling you to call again. Long jobs (1–2 hr videos, project training) typically resolve in 5–10 polls.