> For the complete documentation index, see [llms.txt](https://docs.autommate.com/userguide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.autommate.com/userguide/mcp-and-ai-reference/track-run-status-and-verify-results.md).

# Track run status and verify results

**Direct tool references:** [`runs_search`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/runs-search.md) · [`runs_get`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/runs-get.md) · [`runs_get_latest_error`](https://docs.autommate.com/userguide/mcp-and-ai-reference/tools/runs-get-latest-error.md). These contracts were reviewed against the 21 October 2026 Autom Mate New declaration profile. Historical examples retain their original dates; declared capability is not runtime verification. Check [capabilities and version scope](https://docs.autommate.com/userguide/mcp-and-ai-reference/capabilities-and-version-scope.md) for the active connection.

Monitoring tools read execution evidence. They do not start, cancel, resume, or retry an execution. There is no dedicated blocking wait tool in this connector contract.

### MCP conversations and execution logs

The inspected 21 October Autom Mate New profile does not declare an MCP conversation-log tool. When an MCP run call starts a Hyperflow, the resulting execution is recorded in Monitoring. Use that execution record to inspect the run; it is separate from the full conversation with the AI assistant. The AI provider or client may maintain its own conversation history under its own settings and policies.

### `runs_search`

Read Hyperflow run history, newest first by default. Use `created_from` and `created_to` for an inclusive ISO 8601 time window with the user's UTC offset. For failed runs' messages in the same result, set `include_errors:true`, `status:["failed"]` and page size at most 20.

| Parameter        | Type                                                                        | Required | Meaning                                                                                                                                                            |
| ---------------- | --------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `autom_id`       | string                                                                      | No       | Restrict history to an ID returned by `automs_search`.                                                                                                             |
| `created_from`   | string                                                                      | No       | Inclusive ISO 8601 lower time boundary; include the user's UTC offset for a date-time.                                                                             |
| `created_to`     | string                                                                      | No       | Inclusive ISO 8601 upper time boundary; preserve the same time zone/window.                                                                                        |
| `status`         | array of `completed`, `failed`, `in_progress`, `pending`                    | No       | Requested recorded execution states.                                                                                                                               |
| `include_errors` | boolean                                                                     | No       | Include failed runs' error messages from their summaries. Use with `status:["failed"]`; pages contain at most 20 in this mode.                                     |
| `query`          | string                                                                      | No       | Search value; exact matching rules are not specified by this declaration.                                                                                          |
| `sort_by`        | `autom_name`, `status`, `run_by`, `created_on`, `started_at`, `finished_at` | No       | Sort field; no separate sort-direction parameter is exposed.                                                                                                       |
| `page_size`      | number                                                                      | No       | Requested page size. The older connector rejected values above 50; the current description limits error-enriched pages to at most 20. Do not infer other defaults. |
| `cursor`         | string                                                                      | No       | Opaque continuation returned by the preceding response.                                                                                                            |

Use the operation identifier returned by history to read a particular run. Preserve `scope_note`; results can be limited to Automs created by the connected user.

### `runs_get`

Read one run.

| Parameter         | Type    | Required | Meaning                                                                                                                                                                 |
| ----------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operation_id`    | string  | Yes      | Specific returned execution ID.                                                                                                                                         |
| `include_steps`   | boolean | No       | Request the run's steps; default reads provide summary logs.                                                                                                            |
| `include_step_io` | boolean | No       | With `include_steps:true`, request each step's logged input/output when enabled on the environment. Secrets are masked and each input/output is cut at 2000 characters. |

The default response provides summary logs. `include_steps:true` lists steps; adding `include_step_io:true` requests logged inputs and outputs when the environment enables that feature. Secrets are masked; each logged input/output is cut at 2000 characters. If disabled, `step_io_note` explains the limit. Missing data is not evidence of empty input/output.

Historical examples include action\_count, was\_cancelled and errors, plus steps, steps\_truncated and total\_steps. An older response with 13 actions and two summary steps can have steps\_truncated:false; this describes that returned summary, not every action or untruncated field. See [Read run history and failure evidence](https://docs.autommate.com/userguide/mcp-and-ai-reference/read-run-history-and-failure-evidence.md). Start/end markers alone never prove no work ran.

### `runs_get_latest_error`

Read the latest known failure for an Autom and the available continuity-of-failure context.

| Parameter  | Type   | Required | Meaning                                   |
| ---------- | ------ | -------- | ----------------------------------------- |
| `autom_id` | string | Yes      | Identifier obtained from `automs_search`. |

Failure-history examples place consecutive, last\_success\_at and window\_exhausted inside recent\_failures. When window\_exhausted is true, report “at least” the returned failure count. Otherwise, the count is exact within the search window, not across unlimited history. See [Read run history and failure evidence](https://docs.autommate.com/userguide/mcp-and-ai-reference/read-run-history-and-failure-evidence.md) for the example shape.

Separate the actual error evidence from your hypothesis about its cause. Connection metadata may help investigate credential-related errors, but it cannot validate the remote credential.

### Status is not the business outcome

The search filter accepts the following values. Use the returned status as reported; the tool contract does not publish a complete state-transition model.

| Observed status | Safe interpretation                                         | What it does not prove                                                                                            |
| --------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `pending`       | The recorded run has not reached a completed/failed status. | Why it is pending, or that it will start at a particular time.                                                    |
| `in_progress`   | The run is reported as in progress.                         | Successful completion, a particular current action, or a stuck execution.                                         |
| `completed`     | The runtime reports the execution as completed.             | That an external user, ticket, invoice, or other business outcome is correct without appropriate output/evidence. |
| `failed`        | The runtime reports failure.                                | That no side effects occurred before the failure.                                                                 |

Use the specific run’s status and result to answer execution questions. Agent health, credential state and schedule state are separate diagnostic inputs.

### Bounded monitoring pattern

1. Locate the intended execution and retain its `operation_id` when available.
2. Read its status and available logs.
3. If it is not terminal, wait in the calling application before another read. The connector does not publish a polling interval or service-level guarantee; use a bounded interval appropriate to the task and respect any returned limits.
4. Continue only within an agreed monitoring window. Avoid continuous rapid calls.
5. On `completed` or `failed`, stop polling and inspect the evidence needed for the user's question.
6. If the monitoring window ends first, report the last observed status and observation time. Do not call an unfinished run failed solely because monitoring ended.

For webhook runs without an operation ID in the start response, use `runs_search` to locate the run. Do not rerun the Autom merely to obtain an identifier.

### Reporting format

Keep these facts separate in the response:

* **Requested action:** the Autom and intended inputs.
* **Execution evidence:** operation ID if known, observation time, and reported status.
* **Result evidence:** relevant output/log facts and any destination verification available through an authorized source.
* **Unresolved item:** any ambiguity, missing detail, or follow-up required.

### Worked example: inspect a scheduled service execution

Use this read-only procedure when a service execution has already run. In a check on 14 October 2026, the connector returned a completed scheduled execution with SERVICE-GOVERN, SERVICE-EXECUTE and SERVICE-PROVE entries. The check read existing records; it did not start or change an execution.

1. Use `runs_search` to locate the intended execution. Limit the search to a discovered `autom_id` when available, or use a recognizable Hyperflow name in `query`. For a current investigation, use `created_from` and `created_to` with the intended UTC offset, then compare returned timestamps and identifiers. The dated 14 October observation below remains historical evidence.
2. Copy the `operation_id` from that result. Call `runs_get` with that identifier and `include_steps:true`. Under the current declaration, add `include_step_io:true` for logged inputs/outputs when enabled; the historical example below requested steps only.
3. Compare `status`, `trigger_type`, start and finish timestamps, `errors` and `was_cancelled`. Keep the returned values with the observation time.
4. Read the phase entries in `steps`. Check `action_count`, `total_steps`, `child_count` and `steps_truncated` before deciding how much execution detail the response contains.
5. For the business result, open the matching service case and the relevant action input/output in the product. Verify the expected destination change when applicable. A completed run or a PROVE-labelled step alone does not confirm that business result.

Example request — replace the placeholder with the operation identifier returned by your own search. This placeholder is not a real run identifier.

{% code collapsedlinecount="10" %}

```json
{
  "operation_id": "<operation-id-from-your-search>",
  "include_steps": true
}
```

{% endcode %}

### Read the phase summary correctly

| Returned field in the checked execution          | Interpretation                                                                                                                                                      |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status: completed`; `trigger_type: schedule`    | The runtime reported this scheduled execution as completed. No new execution was started to obtain the result.                                                      |
| `errors: []`; `was_cancelled: false`             | The response contained no error entries and reported that the run was not cancelled. Verify the business outcome separately.                                        |
| `action_count: 8`; `total_steps: 5`              | The response counted eight actions and returned five summary steps. The counts refer to different levels of detail.                                                 |
| SERVICE-GOVERN → SERVICE-EXECUTE → SERVICE-PROVE | These three named phase entries were among the five summary steps. Their presence helps locate the execution phases, but does not expose every action input/output. |
| SERVICE-EXECUTE `child_count: 3`                 | The summary reported nested work under the Execute phase. Inspect the product logs for those action details.                                                        |
| `steps_truncated: false`                         | The returned summary was not truncated. This flag does not convert a phase summary into a complete action trace.                                                    |

Example reply to a user: “The selected scheduled execution is completed. Its summary includes Govern, Execute and Prove, with no error entries returned. I still need the service case and action output to confirm the requested business result.” Adapt the status and findings to the actual response; do not reuse these example values for another run.

For detailed log interpretation, see [Read run history and failure evidence](https://docs.autommate.com/userguide/mcp-and-ai-reference/read-run-history-and-failure-evidence.md).

In a separate controlled test on 14 October 2026, runs\_get reported status: completed while its errors array contained failures and the matching Service Case finished as Failed. The SERVICE-EXECUTE summary also showed has\_error: false despite those errors. Check the errors array and the Case's final outcome together; a completed top-level status or a single phase flag is not an all-clear.
