# uip maestro job

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

`uip maestro job` inspects an individual **Maestro 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 job traces <job-key>
                       [-t, --tenant <name>] [--poll-interval <ms>]
                       [--traces-service <name>] [--pretty]
                       [--login-validity <minutes>]

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

## uip maestro job traces

Stream execution trace events for a running or recently completed job.

### 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. |
| `--pretty` | off | Pretty-print trace events. Without it, each event is emitted as a single JSON line. |
| `--login-validity <minutes>` | `10` | Token-refresh threshold. |

### Behavior

- Writes a heading line: `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 `result.success`, `1` otherwise.

### Examples

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

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

# Slower polling
uip maestro job traces b2c3d4e5-… --poll-interval 5000
```

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

## uip maestro job status

Get the status of a Maestro 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": "MaestroJobStatus",
  "Data": {
    "key":             "b2c3d4e5-…",
    "state":           "Successful",
    "runtimeType":     "…",
    "processType":     "ProcessOrchestration",
    "startTime":       "2025-04-15T10:30:00Z",
    "endTime":         "2025-04-15T10:32:11Z",
    "creationTime":    "2025-04-15T10:29:58Z",
    "inputArguments":  "{}",
    "outputArguments": "{}",
    "info":            "",
    "releaseName":     "InvoiceOrchestration",
    "processKey":      "a1b2c3d4-…",
    "robotName":       "…",
    "hostMachineName": "…"
  }
}
```

With `--detailed`, `Data` is the full Orchestrator job object.

## Examples

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

# Summary once done
uip maestro job status "$JOB_KEY" --folder-key "<folder-key>"

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

## See also

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