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.

Parameters

Name	Type	Required	Default	Description
`workflow_id`	`string`	Yes	—	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.
`run_id`	`string`	No	—	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`	`string`	No	—	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.
`page`	`integer`	No	—	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.
`per_page`	`integer`	No	—	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.

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 — the 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 runs (most recent first)."
    },
    "status": {
      "type": "string",
      "description": "Single-run mode — run status."
    },
    "link_url": {
      "type": "string",
      "format": "uri",
      "description": "URL to the run detail page (single-run mode; also present on each list item)."
    },
    "_step_logs": {
      "type": "array",
      "description": "Single-run mode — per-step execution logs."
    },
    "itemsTotal": {
      "type": "integer",
      "description": "List mode only — total number of runs."
    },
    "_tool_call_logs": {
      "type": "array",
      "description": "Single-run mode — tool call logs."
    },
    "workflow_template_id": {
      "type": "string",
      "format": "uuid",
      "description": "Single-run mode — parent workflow UUID."
    }
  },
  "description": "Workflow run history. Shape depends on whether run_id was supplied. List mode (run_id omitted) populates items + itemsTotal. Single-run mode (run_id supplied) populates id, workflow_template_id, status, _step_logs, and _tool_call_logs."
}

Instructions

Inspect workflow run history. Two modes controlled by run_id presence:

Input roles:

workflow_id: UUID string of the workflow.
run_id: UUID string. If present → single-run detail with step logs and tool call logs. If absent → paginated list of runs.
status: list-mode filter. Ignored in single mode.
page / per_page: list-mode pagination.

Usage patterns:

When the user asks "did my workflow run?": call with just workflow_id (list mode) and look at items[0].status + items[0].completed_at.
When the user asks "what did that run do?": call with workflow_id + run_id (single mode) and read _step_logs and _tool_call_logs.
When troubleshooting failures: filter list mode by status="failed", then pull each detail.
Each run's id is a UUID string. The link_url on each run points to its detail page in Marcora.

Links: present link_url to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.