# uip flow instances

> `uip 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`.

`uip 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](./global-options.md). Exit codes follow the [standard contract](./exit-codes.md).

## Synopsis

```
uip flow instance list                <instance-id>             -f <folder-key> [-l <limit>] [--offset <n>] [--process-key <k>] [--package-id <id>] [--error-code <code>]
uip flow instance get                 <instance-id>             -f <folder-key>
uip flow instance pause               <instance-id>             -f <folder-key> [--comment <text>]
uip flow instance resume              <instance-id>             -f <folder-key> [--comment <text>]
uip flow instance cancel              <instance-id>             -f <folder-key> [--comment <text>]
uip flow instance retry               <instance-id>             -f <folder-key> [--comment <text>]
uip flow instance migrate             <instance-id> <new-version> -f <folder-key> [--comment <text>]
uip flow instance variables           <instance-id>             -f <folder-key> [--parent-element-id <id>]
uip flow instance incidents           <instance-id>             -f <folder-key>
uip flow instance asset               <instance-id>             -f <folder-key>
uip flow instance cursors             <instance-id>             -f <folder-key>
uip flow instance goto                <instance-id> <transitions> -f <folder-key>
uip flow instance element-executions  <instance-id>             -f <folder-key>
```

**`-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 flow instance list

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

#### Options

| Option | Default | Description |
|---|---|---|
| `-l, --limit <n>` | `DEFAULT_PAGE_SIZE` | Number of items to return (1-10000). |
| `--offset <n>` | `0` | Number of items to skip (0-1000000). |
| `--process-key <k>` | — | Filter by process key. |
| `--package-id <id>` | — | Filter by package ID. |
| `--error-code <code>` | — | Filter by error code. |

#### Data shape

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

### uip flow instance get

Fetch a single instance by ID.

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

### uip flow instance pause

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

### uip flow instance resume

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

### uip flow instance cancel

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

### uip flow instance retry

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

### uip flow instance migrate

Migrate an instance to a different package version.

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

**Data shape**: `Code: "InstanceMigrated"`.

### uip 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 flow instance incidents

Get incidents for a specific instance.

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

### uip 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 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 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`.

```bash
uip 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 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

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

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

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

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

## See also

- [`uip flow incidents`](./uip-flow-incidents.md) — read incidents detached from a specific instance
- [`uip flow job`](./uip-flow-job.md) — the job view of an instance run
- [`uip flow process`](./uip-flow-process.md) — start new instances
- [Orchestrator jobs](./uip-orchestrator-jobs.md)
- [Flow overview](./uip-flow.md)