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

# plungeai_execute_workflow

> Execute a CNL workflow (saved workflow_id or ad-hoc workflow_yaml).


Execute a CNL workflow (saved workflow_id or ad-hoc workflow_yaml). Streams progress. Use mode:"async" for long runs (>3 min) — it returns an execution_id to poll with plungeai_get_workflow_status. In ad-hoc YAML, write long strings as block scalars (`prompt: |`) — never hard-wrap a value; structured tool-agents take their card's parameters as task fields alongside `agent:`. Always answers with a structured outcome (never a raw error) — follow the remediation instead of retrying the identical call.

Execute a CNL workflow: a saved one (`workflow_id`) or ad-hoc YAML (`workflow_yaml`). Streams progress. Use `mode:"async"` for long runs (over 3 minutes): it returns an execution id to poll with `plungeai_get_workflow_status`. In ad-hoc YAML, write long strings as block scalars (`prompt: |`) and never hard-wrap a value; structured tool-agents take their card's parameters as task fields next to `agent:`. Always answers with a structured outcome, never a raw error: follow the remediation instead of retrying the identical call.

**Returns.** `ok` with the run's output and the execution-id footer. `ok` with only the execution id for `mode:"async"`. `needs_input` when neither YAML nor id is given, when the saved id is not on your account (``No saved workflow with id `<id>` on this account.``), or when the YAML does not parse. `unavailable` when ad-hoc YAML names an agent that does not exist or is not active, before anything runs. `needs_approval` / `needs_input` when the run pauses for you. A failed run is classified into an outcome; an invalid-YAML failure adds a tip on quoting and block scalars.

Runs a model and costs credits (not verified here):

```bash
curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_execute_workflow","arguments":{"user_request":"run a one-task pong workflow","workflow_yaml":"name: pong-demo\ntasks:\n  - type: task\n    id: t1\n    agent: llm-agent\n    prompt: \"Reply with only the word: pong\"\n"}}}'
```

<Note>
Two parameters recur across the tools: `user_request` (on every tool: a string of up to 4,000 characters, optional; clients should always send it) and `format` (`markdown` by default, or `json`). Both are described once in [Recurring parameters](/mcp-reference/overview#recurring-parameters) on the MCP overview.
</Note>

## Input schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "user_request": {
      "description": "The user's original request, verbatim and in their own words, before you translated it into this call. Always include it — the platform uses it for request context, routing and support diagnostics.",
      "type": "string",
      "maxLength": 4000
    },
    "workflow_yaml": {
      "description": "Ad-hoc CNL workflow YAML. The `workflow:` wrapper is optional — bare top-level name/tasks is accepted and wrapped automatically.",
      "type": "string",
      "maxLength": 262144
    },
    "workflow_id": {
      "type": "string",
      "maxLength": 256
    },
    "input": {
      "type": "string",
      "maxLength": 65536
    },
    "inputs": {
      "type": "object",
      "propertyNames": {
        "type": "string",
        "maxLength": 128
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 8192
      }
    },
    "mode": {
      "type": "string",
      "enum": [
        "sync",
        "async"
      ]
    },
    "format": {
      "default": "markdown",
      "description": "markdown (default): rendered for an AI reader · json: the same outcome as a JSON document in `text` plus `structuredContent`",
      "type": "string",
      "enum": [
        "markdown",
        "json"
      ]
    }
  }
}
```