> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baseten.co/llms.txt
> Use this file to discover all available pages before exploring further.

# baseten loops run

> Manage Loops runs

## create

```sh theme={"system"}
baseten loops run create [OPTIONS]
```

Create a Loops session, a run for the given base model, and the run's paired sampler.

Returns as soon as the resources are provisioned. Both halves finish coming up in the background; poll with 'baseten loops run describe' or watch 'baseten loops run logs'.

### Options

<ParamField body="--base-model" type="TEXT" required>
  HuggingFace ID of the base model to fine-tune (for example 'Qwen/Qwen3-8B').
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--name" type="TEXT">
  Display name for the run. Defaults to the base model.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--replicas" type="INTEGER">
  Number of data-parallel trainer replicas. The trainer deployment runs this many copies of the model's preset node group, so --replicas 4 on a 4-node preset provisions 16 nodes. Defaults to 1.
</ParamField>

<ParamField body="--team" type="TEXT">
  Team name or ID that owns the run's infrastructure. Defaults to the organization's default team.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Create a run for a base model

```sh theme={"system"}
baseten loops run create --base-model Qwen/Qwen3-8B
```

Create a named run with four data-parallel trainer replicas

```sh theme={"system"}
baseten loops run create --base-model Qwen/Qwen3-8B --name experiment-1 --replicas 4
```

### Filter output with `--jq`

Print just the new run's ID

```sh theme={"system"}
baseten loops run create --base-model Qwen/Qwen3-8B --jq '.id'
```

### Output

**Text mode (`--output text`):** On success, prints the new run's ID and base model to stderr; no stdout output.

**JSON mode (`--output json`):** payload type `managementapi.LoopsRun`.

The created run, including its paired sampler.

## list

```sh theme={"system"}
baseten loops run list [OPTIONS]
```

List Loops runs, newest first.

Lists your own runs; pass --org to list every run in the organization, which adds an Owner column. Inactive runs are hidden unless you pass --all.

### Options

<ParamField body="--all" type="BOOL">
  Include inactive runs.
</ParamField>

<ParamField body="--base-model" type="TEXT">
  Only list runs of this base model.
</ParamField>

<ParamField body="--direction" type="TEXT" default="desc">
  Sort order by creation time: 'desc' (newest first) or 'asc' (oldest first).

  One of: `asc`, `desc`
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--org" type="BOOL">
  List every run in the organization, with its owner, instead of only your own.
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

List your active runs

```sh theme={"system"}
baseten loops run list
```

List every run in the organization, including inactive ones

```sh theme={"system"}
baseten loops run list --org --all
```

List runs for one base model, oldest first

```sh theme={"system"}
baseten loops run list --base-model Qwen/Qwen3-8B --direction asc
```

### Filter output with `--jq`

Print just the run IDs

```sh theme={"system"}
baseten loops run list --jq '.runs[].id'
```

### Output

**Text mode (`--output text`):** Table with columns: ID, OWNER (with --org), BASE MODEL, STATUS, CREATED. When no runs match, prints "No Loops runs found." to stderr.

**JSON mode (`--output json`):** payload type `managementapi.ListLoopsRunsResponse`.

## describe

```sh theme={"system"}
baseten loops run describe [OPTIONS]
```

Describe a Loops run by ID, including its paired sampler.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--run-id" type="TEXT" required>
  ID of the Loops run.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Describe a run by ID

```sh theme={"system"}
baseten loops run describe --run-id <run-id>
```

### Filter output with `--jq`

Print the run's sampler base URL

```sh theme={"system"}
baseten loops run describe --run-id <run-id> --jq '.sampler.base_url'
```

### Output

**Text mode (`--output text`):** Field-per-line summary of the run, followed by its sampler when one exists.

**JSON mode (`--output json`):** payload type `managementapi.LoopsRun`.

## deactivate

```sh theme={"system"}
baseten loops run deactivate [OPTIONS]
```

Deactivate a Loops run, tearing down both the run and its paired sampler. Saved checkpoints remain accessible.

Prompts for yes/no confirmation. Pass --yes to skip the prompt. When stdin is not a terminal, --yes is required.

### Options

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--run-id" type="TEXT" required>
  ID of the Loops run.
</ParamField>

<ParamField body="--yes" type="BOOL">
  Skip the interactive confirmation prompt. Required when stdin is not a terminal.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Deactivate a run without the confirmation prompt

```sh theme={"system"}
baseten loops run deactivate --run-id <run-id> --yes
```

### Filter output with `--jq`

Print the deactivated run's base model

```sh theme={"system"}
baseten loops run deactivate --run-id <run-id> --yes --jq '.base_model'
```

### Output

**Text mode (`--output text`):** On success, prints "Deactivated Loops run `id`" to stderr; no stdout output.

**JSON mode (`--output json`):** payload type `managementapi.DeactivateLoopsRunResponse`.

## logs

```sh theme={"system"}
baseten loops run logs [OPTIONS]
```

Fetch logs for a Loops run.

By default returns the run's trainer logs; pass --sampler for the paired sampler's logs instead, which are a separate stream.

By default returns up to --limit lines from the last 30 minutes, newest first. Use --start/--end or --since to scope the window (max 7 days). Use --tail to stream live logs until the run stops producing them or you interrupt with Ctrl-C.

For machine-readable streaming, prefer --output jsonl over --output json.

### Options

<ParamField body="--end" type="TEXT">
  End of the log time range. Accepts ISO 8601; values without a timezone designator are interpreted in the local timezone. Default is now. Window must be at most 7 days.
</ParamField>

<ParamField body="-q, --jq" type="TEXT">
  Filter JSON output with a jq expression; implies --output json (or jsonl for streamed commands)
</ParamField>

<ParamField body="--limit" type="INTEGER" default="5000">
  Maximum number of log lines to return, paging backward from the end of the window. Use 0 for no limit (every log line in the window). Not applicable with --tail.
</ParamField>

<ParamField body="--min-level" type="TEXT">
  Only return logs at or above this severity level.

  One of: `debug`, `info`, `warning`, `error`
</ParamField>

<ParamField body="-o, --output" type="TEXT" default="text">
  Output format

  One of: `text`, `json`, `jsonl`, `none`
</ParamField>

<ParamField body="--profile" type="TEXT">
  Use a specific stored profile for this command, overriding BASETEN\_PROFILE and the current profile
</ParamField>

<ParamField body="--run-id" type="TEXT" required>
  ID of the Loops run.
</ParamField>

<ParamField body="--sampler" type="BOOL">
  Fetch the paired sampler's logs instead of the run's trainer logs.
</ParamField>

<ParamField body="--since" type="TEXT">
  Shortcut for fetching logs from a relative time ago until now. Accepts a duration (e.g. '30m', '1h30m') or '`N`d' (e.g. '3d'). Maximum '7d'. Mutually exclusive with --start and --end.
</ParamField>

<ParamField body="--start" type="TEXT">
  Start of the log time range. Accepts ISO 8601 (e.g. '2026-05-14', '2026-05-14T12:00:00', '2026-05-14T12:00:00Z'). Values without a timezone designator are interpreted in the local timezone. Default is 30 minutes before the end. Window must be at most 7 days.
</ParamField>

<ParamField body="--tail" type="BOOL">
  Stream new logs as they arrive until the run stops producing them or you interrupt with Ctrl-C. Cannot be combined with the time-range or filter flags. For machine-readable streaming, prefer --output jsonl over --output json.
</ParamField>

<ParamField body="-v, --verbose" type="BOOL">
  Enable verbose logging
</ParamField>

### Examples

Print a run's trainer logs over the last hour

```sh theme={"system"}
baseten loops run logs --run-id <run-id> --since 1h
```

Tail the paired sampler's logs

```sh theme={"system"}
baseten loops run logs --run-id <run-id> --sampler --tail
```

### Filter output with `--jq`

Stream just the log messages as a JSONL stream

```sh theme={"system"}
baseten loops run logs --run-id <run-id> --output jsonl --jq '.message'
```

### Output

**Text mode (`--output text`):** One line per log record: "\[YYYY-MM-DD HH:MM:SS]: (replica) message".

**JSON mode (`--output json`):** payload type `managementapi.Log`.