Workflows
Workflows

run_workflow

Manually dispatch a workflow run. Creates a workflow_run row and dispatches a Managed Agents session. Returns the run row — check .status to know what happened.

Input Schema

{
  "type": "object",
  "required": [
    "workflow_id"
  ],
  "properties": {
    "workflow_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the workflow template to run."
    },
    "input_values": {
      "type": "object",
      "description": "Values for the workflow's declared inputs, if any.",
      "additionalProperties": true
    }
  },
  "additionalProperties": false
}

Output Schema

{
  "type": "object",
  "required": [
    "id",
    "workflow_template_id",
    "status",
    "link_url"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Workflow run UUID. Use as run_id in get_workflow_runs (single mode)."
    },
    "status": {
      "enum": [
        "running",
        "failed",
        "skipped"
      ],
      "type": "string"
    },
    "link_url": {
      "type": "string",
      "format": "uri"
    },
    "error_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Failure cause when status is failed, else null."
    },
    "trigger_type": {
      "type": "string",
      "description": "How the run was triggered. manual for this tool."
    },
    "error_summary": {
      "type": "string"
    },
    "runner_session_id": {
      "type": "string"
    },
    "workflow_template_id": {
      "type": "string",
      "format": "uuid"
    }
  }
}

Instructions

Manually run a workflow now. Creates a workflow run and dispatches a Managed Agents session. Inspect the returned status to know what happened.

Status meanings: running = dispatch succeeded, a session is live; failed = dispatch failed, read error_reason for the cause; skipped = the runner decided no work was needed (rare for manual runs).

Parameters:

  • workflow_id (string uuid, required): UUID of the workflow to run
  • input_values (object, optional): Object matching the workflow's declared inputs schema. Pass {} or omit for workflows with no inputs. Call get_workflow first if unsure

Output: The workflow run object.

  • id (string uuid): Workflow run UUID. Use as run_id in get_workflow_runs (single mode) to inspect the run
  • workflow_template_id (string uuid): Parent workflow UUID
  • status (string): running, failed, or skipped
  • trigger_type (string): How the run was triggered (manual here)
  • runner_session_id (string): Managed Agents session ID for the run
  • error_reason (string or null): Failure cause when status is failed, else null
  • error_summary (string): Human-readable error summary
  • link_url (string uri): Direct URL to view this run in Marcora
Scroll to Top