# uip maestro flow job

> Syntax and options for `uip maestro flow job`, which streams execution traces and fetches detailed status for individual Flow jobs.

`uip maestro flow job` inspects an individual **Flow job** — one execution attempt of a process instance — by streaming its traces or fetching its detailed status.

All subcommands require `uip login` and honor [global options](./global-options.md). Exit codes follow the [standard contract](./exit-codes.md).

## Synopsis

```
uip maestro flow job traces <job-key>
                    [-t, --tenant <name>] [--poll-interval <ms>]
                    [--traces-service <name>] [--pretty]
                    [--login-validity <minutes>]

uip maestro flow job status <job-key>
                    [-t, --tenant <name>] [--folder-key <key>] [--detailed]
                    [--login-validity <minutes>]
```

## uip maestro flow job traces

Stream execution trace events for a running or recently completed job. Lines stream to stderr as they arrive; the final state and duration are also streamed.

### Arguments

- `<job-key>` *(required)* — job key (GUID from `process run`).

### Options

| Option | Default | Description |
|---|---|---|
| `-t, --tenant <name>` | authenticated tenant | Tenant name. |
| `--poll-interval <ms>` | `2000` | Polling interval. Must be a positive number. |
| `--traces-service <name>` | `llmopstenant_` | Traces service name (advanced; override only when directed). |
| `--pretty` | off | Pretty-print trace events. Without it, each event is emitted as a single JSON line — friendly for piping into `jq`. |
| `--login-validity <minutes>` | `10` | Token-refresh threshold. |

### Behavior

- Writes a heading line to stderr: `Streaming traces for job: <key>  Polling every Ns...`
- Streams each trace event via `ScreenLogger.progress` (stderr).
- On completion, emits `Job <key>: <finalState> (<durationMs>ms)`.
- Exit code: `0` if the job succeeded, `1` otherwise (per `result.success`).

### Examples

```bash
# Raw JSON lines — best for piping
uip maestro flow job traces b2c3d4e5-… | jq -c 'select(.level=="error")'

# Human-readable
uip maestro flow job traces b2c3d4e5-… --pretty

# Slower polling for quiet jobs
uip maestro flow job traces b2c3d4e5-… --poll-interval 5000
```

**Output**: traces are streamed directly — no final `Data` payload.

## uip maestro flow job status

Get the status of a Flow job. Returns a curated 14-field summary by default; `--detailed` returns the full Orchestrator response.

### Arguments

- `<job-key>` *(required)* — job key (GUID).

### Options

| Option | Default | Description |
|---|---|---|
| `-t, --tenant <name>` | authenticated tenant | Tenant name. |
| `--folder-key <key>` | authenticated folder | Folder key (GUID). |
| `--detailed` | off | Return the full response instead of the 14-field summary. |
| `--login-validity <minutes>` | `10` | Token-refresh threshold. |

### Data shape (default summary)

```json
{
  "Code": "FlowJobStatus",
  "Data": {
    "key":             "b2c3d4e5-…",
    "state":           "Successful",
    "runtimeType":     "…",
    "processType":     "Flow",
    "startTime":       "2025-04-15T10:30:00Z",
    "endTime":         "2025-04-15T10:32:11Z",
    "creationTime":    "2025-04-15T10:29:58Z",
    "inputArguments":  "{}",
    "outputArguments": "{}",
    "info":            "",
    "releaseName":     "InvoiceFlow",
    "processKey":      "a1b2c3d4-…",
    "robotName":       "…",
    "hostMachineName": "…"
  }
}
```

With `--detailed`, `Data` is the full Orchestrator job object (all fields, unflattened).

:::note
The full detailed-response shape is whatever Orchestrator returns and is not strictly typed by the CLI. Field presence may drift between Orchestrator versions — for scripts that parse specific fields, query defensively and pin `@uipath/cli` in CI.
:::

## Examples

```bash
# Start a job, capture the key, stream traces to completion
JOB_KEY=$(uip maestro flow process run "InvoiceFlow.flow.Flow:1.0.0" "<folder-key>" \
           --inputs '{}' --output-filter "jobKey" --output plain)
uip maestro flow job traces "$JOB_KEY" --pretty

# Get the summary once the job is done
uip maestro flow job status "$JOB_KEY" --folder-key "<folder-key>"

# Full response
uip maestro flow job status "$JOB_KEY" --detailed
```

## See also

- [`uip maestro flow process run`](./uip-maestro-flow-process.md#uip-maestro-flow-process-run) — start a job
- [`uip maestro flow instance`](./uip-maestro-flow-instances.md) — the instance view of the same execution
- [Orchestrator jobs](./uip-orchestrator-jobs.md)
- [Flow overview](./uip-maestro-flow.md)