UiPath Documentation
uipath-cli
latest
false
UiPath CLI user guide

uip maestro flow instance

Syntax and options for `uip maestro flow instance`, which inspects and steers individual Flow process instances.

uip maestro flow instance inspects and steers individual process instances — one execution of a published Flow process. The command name is singular (instance) even though the sidebar entry says instances.

All subcommands require uip login and honor global options. Exit codes follow the standard contract.

This page shares its implementation with uip maestro bpmn instance — the same defects and fixes apply to both pages.

Synopsis​

uip maestro flow instance list                <instance-id>             -f <folder-key> [-l <limit>] [--next-page <cursor>] [--process-key <k>] [--package-id <id>] [--error-code <code>] [--status <status>]... [--from-date <iso-8601>] [--to-date <iso-8601>]
uip maestro flow instance get                 <instance-id>             -f <folder-key>
uip maestro flow instance pause               <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance resume              <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance cancel              <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance retry               <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance migrate             <instance-id> <new-version> -f <folder-key> [--comment <text>]
uip maestro flow instance variables           <instance-id>             -f <folder-key> [--parent-element-id <id>]
uip maestro flow instance variables-set       <instance-id>             -f <folder-key> --inputs <json|@file>
uip maestro flow instance variables-all       <instance-id>             -f <folder-key>
uip maestro flow instance global-variables    <instance-id>             -f <folder-key>
uip maestro flow instance incidents           <instance-id>             -f <folder-key>
uip maestro flow instance asset               <instance-id>             -f <folder-key>
uip maestro flow instance cursors             <instance-id>             -f <folder-key>
uip maestro flow instance goto                <instance-id> <transitions> -f <folder-key>
uip maestro flow instance element-executions  <instance-id>             -f <folder-key>
uip maestro flow instance element cancel      <instance-id> <element-id> -f <folder-key> [--comment <text>]
uip maestro flow instance element retry       <instance-id> <element-id> -f <folder-key> [--comment <text>]
uip maestro flow instance message send        -f <folder-key> [--inputs <json|@file>]
uip maestro flow instance list                <instance-id>             -f <folder-key> [-l <limit>] [--next-page <cursor>] [--process-key <k>] [--package-id <id>] [--error-code <code>] [--status <status>]... [--from-date <iso-8601>] [--to-date <iso-8601>]
uip maestro flow instance get                 <instance-id>             -f <folder-key>
uip maestro flow instance pause               <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance resume              <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance cancel              <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance retry               <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance migrate             <instance-id> <new-version> -f <folder-key> [--comment <text>]
uip maestro flow instance variables           <instance-id>             -f <folder-key> [--parent-element-id <id>]
uip maestro flow instance variables-set       <instance-id>             -f <folder-key> --inputs <json|@file>
uip maestro flow instance variables-all       <instance-id>             -f <folder-key>
uip maestro flow instance global-variables    <instance-id>             -f <folder-key>
uip maestro flow instance incidents           <instance-id>             -f <folder-key>
uip maestro flow instance asset               <instance-id>             -f <folder-key>
uip maestro flow instance cursors             <instance-id>             -f <folder-key>
uip maestro flow instance goto                <instance-id> <transitions> -f <folder-key>
uip maestro flow instance element-executions  <instance-id>             -f <folder-key>
uip maestro flow instance element cancel      <instance-id> <element-id> -f <folder-key> [--comment <text>]
uip maestro flow instance element retry       <instance-id> <element-id> -f <folder-key> [--comment <text>]
uip maestro flow instance message send        -f <folder-key> [--inputs <json|@file>]

-f, --folder-key <key> is required on every subcommand.

Common options​

  • -f, --folder-key <key> (required) — folder key (GUID).
  • --comment <text> (operation commands only) — optional comment recorded with the operation. Sent as an empty string if omitted.

Subcommands​

uip maestro flow instance list​

List instances in a folder, scoped to Flow processes (processType=Flow).

Options​
OptionDefaultDescription
-l, --limit <n>DEFAULT_PAGE_SIZENumber of items to return. Bounded at 1-500 — stricter than this CLI's usual 1-10000 convention, because the instances API pages by cursor rather than offset.
--next-page <cursor>—Cursor from a previous response's Pagination.NextPage. This API does not support --offset at all — a non-zero --offset fails fast with an error telling you to use --next-page instead.
--process-key <k>—Filter by process key (GUID). For the dotted package identifier, use --package-id.
--package-id <id>—Filter by package ID.
--error-code <code>—Filter by error code.
--status <status>—Filter by instance status. Repeatable (OR-semantics). Values: Canceling, Cancelled, Completed, Faulted, Paused, Pausing, Pending, Resuming, Retrying, Running, Upgrading.
--from-date <iso-8601>—Only include instances started at or after this timestamp, e.g. 2026-01-01T00:00:00Z.
--to-date <iso-8601>—Only include instances started at or before this timestamp.
Data shape​

Code: "InstanceList", Data is an array of process-instance objects.

uip maestro flow instance get​

Fetch a single instance by ID.

Data shape: Code: "InstanceGet", Data is the process-instance object.

uip maestro flow instance pause​

Pause a running instance. Data shape: Code: "InstancePaused".

uip maestro flow instance resume​

Resume a paused instance. Data shape: Code: "InstanceResumed".

uip maestro flow instance cancel​

Cancel a running instance. Data shape: Code: "InstanceCanceled".

uip maestro flow instance retry​

Retry a faulted instance. Data shape: Code: "InstanceRetried".

uip maestro flow instance migrate​

Migrate an instance to a different package version.

Arguments: <instance-id>, <new-version> (target package version).

Data shape: Code: "InstanceMigrated".

uip maestro flow instance variables​

Get variables for an instance.

Options: --parent-element-id <id> — filter variables by parent element.

Data shape: Code: "InstanceVariables", Data carries the instance variables payload.

uip maestro flow instance variables-set​

Patch (partially update) variables for an instance.

Options​
OptionDescription
--inputs <value>Patch-variables payload as a JSON string, an @file path, or piped via stdin.
Data shape​

Code: "InstanceVariablesSet".

uip maestro flow instance variables-all​

Get all variables for an instance, including subprocess variables (unlike variables, which is scoped to the top-level process unless --parent-element-id is passed).

Data shape​

Code: "InstanceVariablesAll".

uip maestro flow instance global-variables​

Get an instance's global variables (shared across the whole process, not scoped to any element).

Data shape​

Code: "InstanceGlobalVariables".

uip maestro flow instance element cancel​

Cancel a specific element within a running instance, rather than the whole instance.

Arguments​
  • <instance-id> (required)
  • <element-id> (required)
Options​
  • --comment <text> — optional comment recorded with the operation.
Data shape​

Code: "ElementCanceled".

uip maestro flow instance element retry​

Retry a specific faulted element within an instance, rather than retrying the whole instance.

Arguments​
  • <instance-id> (required)
  • <element-id> (required)
Options​
  • --comment <text> — optional comment recorded with the operation.
Data shape​

Code: "ElementRetried".

uip maestro flow instance message send​

Send a message to workflow subscriptions listening on this folder — used to deliver an external event into a running Flow (for example, a webhook payload the process is waiting on).

Options​
OptionDescription
-f, --folder-key <key>(required) Folder key (GUID).
--inputs <value>Message payload as a JSON string, an @file path, or piped via stdin.
Data shape​

Code: "MessageSent".

uip maestro flow instance incidents​

Get incidents for a specific instance.

Data shape: Code: "InstanceIncidents", Data is an array of incident objects.

uip maestro flow instance asset​

Fetch the Flow definition (the .flow asset) attached to this instance's release — useful when debugging to see the exact graph the instance ran.

Data shape: Code: "InstanceAsset", Data is the Flow JSON.

uip maestro flow instance cursors​

Get current execution cursor positions — which element(s) the instance is paused at.

Data shape: Code: "InstanceCursors", Data lists the current cursor positions.

uip maestro flow instance goto​

Move an execution cursor from one element to another. Useful for recovering a faulted instance by skipping or retrying specific nodes.

Arguments​
  • <instance-id> (required)
  • <transitions> (required) — JSON array of transitions, each with sourceElementId and targetElementId.
uip maestro flow instance goto c3d4e5f6-… \
  '[{"sourceElementId":"Node_1","targetElementId":"Node_3"}]' \
  --folder-key c3d4e5f6-…
uip maestro flow instance goto c3d4e5f6-… \
  '[{"sourceElementId":"Node_1","targetElementId":"Node_3"}]' \
  --folder-key c3d4e5f6-…

The CLI validates the JSON parses and each entry has both IDs before calling the API.

Data shape​

Code: "InstanceGoto".

uip maestro flow instance element-executions​

Get the per-element execution history for an instance (what ran, when, and with what outcome).

Data shape​

Code: "InstanceElementExecutions", Data is the per-element execution history.

Examples​

# Paginate through instances for a specific process
uip maestro flow instance list --folder-key <k> --process-key "InvoiceFlow.flow.Flow:1.0.0" --limit 50

# Pause, fix, resume
uip maestro flow instance pause   <id> --folder-key <k> --comment "Investigating"
uip maestro flow instance resume  <id> --folder-key <k>

# Skip a faulted node by moving the cursor forward, then retry
uip maestro flow instance cursors <id> --folder-key <k>
uip maestro flow instance goto    <id> '[{"sourceElementId":"A","targetElementId":"C"}]' --folder-key <k>
uip maestro flow instance retry   <id> --folder-key <k>

# Upgrade a long-running instance to a new package version
uip maestro flow instance migrate <id> "1.2.0" --folder-key <k> --comment "Patch release"
# Paginate through instances for a specific process
uip maestro flow instance list --folder-key <k> --process-key "InvoiceFlow.flow.Flow:1.0.0" --limit 50

# Pause, fix, resume
uip maestro flow instance pause   <id> --folder-key <k> --comment "Investigating"
uip maestro flow instance resume  <id> --folder-key <k>

# Skip a faulted node by moving the cursor forward, then retry
uip maestro flow instance cursors <id> --folder-key <k>
uip maestro flow instance goto    <id> '[{"sourceElementId":"A","targetElementId":"C"}]' --folder-key <k>
uip maestro flow instance retry   <id> --folder-key <k>

# Upgrade a long-running instance to a new package version
uip maestro flow instance migrate <id> "1.2.0" --folder-key <k> --comment "Patch release"

See also​

Was this page helpful?

Connect

Need help? Support

Want to learn? UiPath Academy

Have questions? UiPath Forum

Stay updated