MCP Tools
Workflows

get_workflow_runs

Inspect a workflow's run history — either a paginated list of runs, or the detailed step and tool-call logs for a single run. Useful for checking whether a workflow ran and for troubleshooting failures.

Input Schema

{
  "type": "object",
  "required": [
    "workflow_id"
  ],
  "properties": {
    "page": {
      "type": "integer",
      "description": "1-based page number through the run list, which is ordered newest first. Defaults to 1, so you only need it to reach runs older than the first page. Ignored when `run_id` is supplied."
    },
    "run_id": {
      "type": "string",
      "description": "UUID of one specific run to inspect in full — its step-by-step logs, tool calls and the agent's messages. Pass it when the user asks what a particular run actually did. Omit it to get the paginated list of runs instead."
    },
    "status": {
      "type": "string",
      "description": "Restricts the run list to a single exact status: \"pending\", \"running\", \"succeeded\", \"failed\" or \"skipped\". Use \"failed\" when troubleshooting, or \"running\" to see whether something is in flight. Ignored when `run_id` is supplied."
    },
    "per_page": {
      "type": "integer",
      "description": "How many runs to return per page. Defaults to 20 when omitted or when the value is not a positive number; set it low (for example 5) when you only need the most recent few. Ignored when `run_id` is supplied."
    },
    "workflow_id": {
      "type": "string",
      "description": "UUID of the workflow whose run history you want. Required. It scopes the list of runs; when you also pass `run_id`, the run is looked up by that id alone and this value is not used to filter."
    }
  }
}

Output Schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Single-run mode only. Run UUID."
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string"
          },
          "link_url": {
            "type": "string",
            "format": "uri"
          },
          "workflow_template_id": {
            "type": "string",
            "format": "uuid"
          }
        }
      },
      "description": "List mode only. Array of run summaries."
    },
    "status": {
      "type": "string",
      "description": "Single-run mode only. Run status."
    },
    "link_url": {
      "type": "string",
      "format": "uri",
      "description": "Single-run mode only. Direct URL to view this run."
    },
    "_step_logs": {
      "type": "array",
      "description": "Single-run mode only. Step execution logs."
    },
    "itemsTotal": {
      "type": "integer",
      "description": "List mode only. Total number of matching runs."
    },
    "_tool_call_logs": {
      "type": "array",
      "description": "Single-run mode only. Tool call logs."
    },
    "workflow_template_id": {
      "type": "string",
      "format": "uuid",
      "description": "Single-run mode only."
    }
  },
  "description": "Shape depends on mode. List mode (run_id omitted): items + itemsTotal. Single-run mode (run_id supplied): id, workflow_template_id, status, _step_logs, _tool_call_logs, link_url."
}

Instructions

Inspect workflow run history. Two modes, controlled by whether run_id is supplied: omit it for a paginated list of runs; supply it for a single run's detail including step logs and tool-call logs.

Parameters:

  • workflow_id (string uuid, required): UUID of the workflow
  • run_id (string uuid, optional): If supplied → single-run detail; if omitted → paginated list of runs
  • status (string, optional): List-mode filter (e.g. "failed"). Ignored in single mode
  • page (integer, optional): List-mode page number (default 1)
  • per_page (integer, optional): List-mode page size (default 20)

Output: An object whose shape depends on the mode:

  • List mode (run_id omitted): items — an array of runs, each { id, workflow_template_id, status, link_url } — plus itemsTotal (integer).
  • Single-run mode (run_id supplied): id, workflow_template_id, status, _step_logs (array), _tool_call_logs (array), and link_url.
Scroll to Top