--- url: /en/api/cli-swanlab-api.md --- # swanlab api ```bash swanlab api [OPTIONS] COMMAND ARGS [ARGS] ``` `swanlab api` is the CLI implementation of the [OpenAPI](./py-api.md), allowing direct manipulation of cloud **workspace / project / experiment / user / self-hosted** resources from the command line. > Authentication follows the same logic as the Python API: pass `--api-key` / `--host` explicitly, or use the `swanlab login` local session. See [Authentication](./py-api.md). ## Subcommand Overview ### workspace — Workspace | Subcommand | Description | | --------------------------------------- | ------------------ | | `swanlab api workspace info ` | Get workspace info | ### project — Project | Subcommand | Description | | --------------------------------- | ------------------------------- | | `swanlab api project info ` | Get project info | | `swanlab api project list` | List projects under a workspace | | `swanlab api project create` | Create a project | ### run — Experiment | Subcommand | Description | | --------------------------------------- | ---------------------------------------------------------------------------------------- | | `swanlab api run info ` | Get experiment info | | `swanlab api run list ` | List experiments under a project | | `swanlab api run filter ` | Filter experiments by query | | `swanlab api run metrics` | Get experiment scalar metrics | | `swanlab api run summary` | Get experiment metric summaries | | `swanlab api run series` | List experiment metric keys | | `swanlab api run column` | Get a single experiment column (⚠️ deprecated; not applicable to multi-view experiments) | | `swanlab api run columns` | List experiment columns (⚠️ deprecated; not applicable to multi-view experiments) | | `swanlab api run medias` | Get experiment media metrics | | `swanlab api run histograms` | Get experiment histogram metrics | | `swanlab api run logs` | Get experiment console logs | | `swanlab api run export-logs` | Export experiment logs as a file | ### user — User | Subcommand | Description | | ----------------------- | --------------------- | | `swanlab api user info` | Get current user info | ### self-hosted — Self-Hosted Management > Requires super admin privileges. | Subcommand | Description | | ----------------------------------------- | -------------------- | | `swanlab api self-hosted info` | Get instance info | | `swanlab api self-hosted create-user` | Create a user | | `swanlab api self-hosted list-users` | List all users | | `swanlab api self-hosted list-projects` | List all projects | | `swanlab api self-hosted summary` | System usage summary | | `swanlab api self-hosted list-workspaces` | List all workspaces | ## Common Options All `swanlab api` subcommands support: | Option | Description | | ----------------- | ------------------------------------------------------------------------- | | `-h`, `--host` | SwanLab server host address | | `-k`, `--api-key` | API key; takes precedence over local login | | `--save` | Save output as JSON file; pass a filename or omit for auto-generated name | ## Subcommand Reference ### workspace info Get detailed information about a workspace. ```bash swanlab api workspace info [OPTIONS] ``` | Argument/Option | Type | Description | | --------------- | ---------- | ------------------------------------------------------------------------- | | `username` | Positional | Workspace username (unique ID) | | `--save` | Option | Save output as JSON file; pass a filename or omit for auto-generated name | ```bash # View workspace info swanlab api workspace info my-team # Save to file swanlab api workspace info my-team --save workspace.json ``` ### project info Get detailed information about a project. ```bash swanlab api project info [OPTIONS] ``` | Argument/Option | Type | Description | | --------------- | ---------- | --------------------------------------------- | | `path` | Positional | Project path, format: `username/project-name` | | `--save` | Option | Save output as JSON file | ```bash swanlab api project info my-team/image-classification ``` ### project list List all projects under a workspace. ```bash swanlab api project list [OPTIONS] ``` | Option | Type | Default | Description | | -------------------- | ------ | ---------------------- | -------------------------------------------------------- | | `--workspace` | `str` | Current logged-in user | Workspace username | | `--page_num` / `-n` | `int` | `1` | Page number | | `--page_size` / `-s` | `str` | `"20"` | Page size; valid values: `"10"`, `"20"`, `"50"`, `"100"` | | `--all` | Flag | `False` | Auto-paginate, fetch all projects | | `--save` | Option | — | Save output as JSON file | ```bash # List projects for current workspace swanlab api project list # List projects for a specific workspace, 50 per page swanlab api project list --workspace my-team --page_size 50 # Fetch all projects swanlab api project list --workspace my-team --all ``` ### project create Create a new project in a workspace. ```bash swanlab api project create [OPTIONS] ``` | Option | Type | Default | Description | | ---------------------- | ------ | ---------------------- | ------------------------------------------------ | | `-n` / `--name` | `str` | Required | Project name (1–100 chars, `0-9a-zA-Z-_.+` only) | | `-v` / `--visibility` | `str` | `"PRIVATE"` | Visibility: `PUBLIC` or `PRIVATE` | | `-d` / `--description` | `str` | `None` | Project description | | `-w` / `--workspace` | `str` | Current logged-in user | Workspace username | | `--save` | Option | — | Save output as JSON file | ```bash # Create a private project swanlab api project create -n my-project -v PRIVATE # Create a public project in a specific workspace swanlab api project create -n my-project -v PUBLIC -w my-team -d "Image classification experiments" ``` ### run info Get detailed information about an experiment. ```bash swanlab api run info [OPTIONS] ``` | Argument/Option | Type | Description | | --------------- | ---------- | -------------------------------------------------------------- | | `path` | Positional | Experiment path, format: `username/project-name/experiment-id` | | `--save` | Option | Save output as JSON file | ```bash swanlab api run info my-team/image-classification/abc123 ``` ### run list List all experiments under a project. ```bash swanlab api run list [OPTIONS] ``` | Argument/Option | Type | Default | Description | | -------------------- | ---------- | -------- | --------------------------------------------- | | `project_path` | Positional | Required | Project path, format: `username/project-name` | | `--page_num` / `-n` | `int` | `1` | Page number | | `--page_size` / `-s` | `str` | `"20"` | Page size | | `--all` | Flag | `False` | Auto-paginate, fetch all experiments | | `--save` | Option | — | Save output as JSON file | ```bash # List experiments in a project swanlab api run list my-team/image-classification # Fetch all experiments swanlab api run list my-team/image-classification --all ``` ### run filter Query experiments by filter conditions. Use a JSON array to specify one or more filter rules. ```bash swanlab api run filter --filter_query [OPTIONS] ``` | Argument/Option | Type | Description | | ----------------------- | ---------- | ------------------------------------------------------------- | | `project_path` | Positional | Required, project path, format: `username/project-name` | | `--filter_query` / `-f` | `str` | Required, filter conditions (JSON array or path to JSON file) | | `--save` | Option | Save output as JSON file | Each filter rule is a JSON object: ```json { "key": "", "type": "STABLE | CONFIG | SCALAR", "op": "EQ | NEQ | GT | LT | GTE | LTE | CONTAIN | NOT_CONTAIN", "value": [""] } ``` `type` value reference: | type | key values | value description | | -------- | ----------------------------------------------------------------------------------------------------- | ----------------------------- | | `STABLE` | `state`, `name`, `description`, `show`, `pin`, `labels`, `createdAt`, `updatedAt`, `finishedAt`, etc. | The corresponding field value | | `CONFIG` | Config parameter name (e.g. `param_2`, **no** `config.` prefix) | Config parameter value | | `SCALAR` | Scalar metric name (e.g. `loss`) | Metric value | ```bash # Query finished experiments swanlab api run filter my-team/image-classification \ -f '[{"key": "state", "type": "STABLE", "op": "EQ", "value": ["FINISHED"]}]' # Read filter conditions from file swanlab api run filter my-team/image-classification -f ./filter.json ``` ### run metrics Get scalar metrics for an experiment, returned as JSON. ```bash swanlab api run metrics --keys [OPTIONS] ``` | Argument/Option | Type | Default | Description | | -------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `path` | Positional | Required | Experiment path | | `--keys` | `str` | Required | Comma-separated metric keys, e.g. `"loss,acc"` | | `--sample` / `-s` | `int` | `1500` | Sample size; auto-capped if exceeded | | `--ignore-timestamp` | Flag | `False` | Remove timestamp field from metric data | | `--all` | Flag | `False` | Fetch full data (CSV export for scalars) | | `--x-axis` | `str` | `"step"` | X axis of the returned data: `step` (default), built-in axes `time` / `relative_time`, or a custom X-axis metric key (`swanlab >= 0.10.1`) | | `--range-type` | `str` | `None` | Range query type: `step`, `timestamp`, or `custom` (custom X-axis value domain; requires `--x-axis`) | | `--range-start` | `float` | `None` | Range start (inclusive), step number, unix timestamp in ms, or custom X-axis value | | `--range-end` | `float` | `None` | Range end (inclusive), step number, unix timestamp in ms, or custom X-axis value | | `--range-head` | `int` | `None` | Return first N data points | | `--range-tail` | `int` | `None` | Return last N data points | | `--range-last` | `int` | `None` | Data from the last N milliseconds (mutually exclusive with `--range-start`/`--range-end`) | | `--save` | Option | — | Save output as JSON file | **Notes:** * `--range-head` and `--range-tail` are mutually exclusive. * `--range-last` is mutually exclusive with `--range-start`/`--range-end`. * `--range-head`/`--range-tail` can be combined with `--range-start`/`--range-end` or `--range-last` (range filter is applied first, then truncation). * `--range-start` and `--range-end` work with `--range-type` (`step` or `timestamp`); timestamps are in milliseconds. * `--range-type custom` is only valid when `--x-axis` is a custom metric key; in that case `--range-start`/`--range-end` accept any floats (including negatives). `step` / `timestamp` types require non-negative integers. ```bash # Get loss metric (default 1500 samples) swanlab api run metrics my-team/image-classification/abc123 --keys loss # Get multiple metrics, 500 samples swanlab api run metrics my-team/image-classification/abc123 --keys loss,acc -s 500 # Range query by step swanlab api run metrics my-team/image-classification/abc123 \ --keys loss --range-type step --range-start 100 --range-end 500 # Data from the last 5 minutes swanlab api run metrics my-team/image-classification/abc123 \ --keys loss --range-last 300000 # Get last 200 data points swanlab api run metrics my-team/image-classification/abc123 \ --keys loss --range-tail 200 # Step range + first 50 points swanlab api run metrics my-team/image-classification/abc123 \ --keys loss --range-type step --range-start 0 --range-end 500 --range-head 50 # Custom X axis: plot loss against epoch swanlab api run metrics my-team/image-classification/abc123 \ --keys loss --x-axis epoch # Range filter on the custom X-axis value domain (floats allowed) swanlab api run metrics my-team/image-classification/abc123 \ --keys loss --x-axis lr --range-type custom --range-start 0.0001 --range-end 0.001 ``` ### run summary Get scalar metric summaries for an experiment (final value, min, max, etc.). ```bash swanlab api run summary [OPTIONS] ``` | Argument/Option | Type | Description | | --------------- | ---------- | ---------------------------------------------- | | `path` | Positional | Experiment path | | `--keys` | `str` | Comma-separated metric keys; omit for all keys | | `--save` | Option | Save output as JSON file | ```bash # Get summary for all metrics swanlab api run summary my-team/image-classification/abc123 # Get summary for specific metrics swanlab api run summary my-team/image-classification/abc123 --keys loss,acc ``` ### run series List metric keys of an experiment (recommended in `0.9.0+`, replacing `column` / `columns`). Supports filtering by metric type, class, and keyword. ```bash swanlab api run series [OPTIONS] ``` | Argument/Option | Type | Default | Description | | --------------- | ---------- | ---------- | ---------------------------------------------------------- | | `path` | Positional | Required | Experiment path | | `--type` | `str` | `"scalar"` | Metric type: `scalar`, `media` or `histogram` | | `--class` | `str` | `"custom"` | Metric class: `custom` or `system` | | `--search` | `str` | `None` | Fuzzy search keyword (case-insensitive, matches key names) | | `--save` | Option | — | Save output as JSON file | ```bash # List all custom scalar keys swanlab api run series my-team/image-classification/abc123 # Fuzzy search swanlab api run series my-team/image-classification/abc123 --search loss # List system metrics only swanlab api run series my-team/image-classification/abc123 --class system # List media metrics swanlab api run series my-team/image-classification/abc123 --type media # List histogram metrics swanlab api run series my-team/image-classification/abc123 --type histogram ``` ### run column ::: warning Not recommended Since swanlab `0.9.0` (multi-view version), `column` / `columns` are no longer recommended and do not apply to multi-view experiments. Use [`series`](#run-series) instead. ::: Get a single metric column for an experiment. ```bash swanlab api run column --key [OPTIONS] ``` | Argument/Option | Type | Default | Description | | --------------- | ---------- | ---------- | -------------------------------------------------- | | `path` | Positional | Required | Experiment path | | `--key` | `str` | Required | Column key name | | `--class` | `str` | `"CUSTOM"` | Column class: `CUSTOM` or `SYSTEM` | | `--type` | `str` | `None` | Column data type: `FLOAT`, `STRING`, `IMAGE`, etc. | | `--save` | Option | — | Save output as JSON file | ```bash swanlab api run column my-team/image-classification/abc123 --key loss ``` ### run columns ::: warning Not recommended Since swanlab `0.9.0` (multi-view version), `column` / `columns` are no longer recommended and do not apply to multi-view experiments. Use [`series`](#run-series) instead. ::: List all metric columns for an experiment. ```bash swanlab api run columns [OPTIONS] ``` | Argument/Option | Type | Default | Description | | -------------------- | ---------- | ---------- | ------------------------------------------ | | `path` | Positional | Required | Experiment path | | `--page_num` / `-n` | `int` | `1` | Page number | | `--page_size` / `-s` | `str` | `"20"` | Page size | | `--search` | `str` | `None` | Fuzzy search keyword (matches column name) | | `--class` | `str` | `"CUSTOM"` | Column class filter | | `--type` | `str` | `None` | Column data type filter | | `--all` | Flag | `False` | Auto-paginate, fetch all columns | | `--save` | Option | — | Save output as JSON file | ```bash # List all columns swanlab api run columns my-team/image-classification/abc123 # Fuzzy search swanlab api run columns my-team/image-classification/abc123 --search loss # List SYSTEM FLOAT columns only swanlab api run columns my-team/image-classification/abc123 \ --class SYSTEM --type FLOAT --all ``` ### run medias Get media metrics (images, audio, etc.) for an experiment. Returns presigned URLs. ```bash swanlab api run medias --keys [OPTIONS] ``` | Argument/Option | Type | Default | Description | | --------------- | ---------- | -------- | ------------------------------------------------ | | `path` | Positional | Required | Experiment path | | `--keys` | `str` | Required | Comma-separated media keys, e.g. `"image,audio"` | | `--step` / `-s` | `int` | `0` | Step number | | `--all` | Flag | `False` | Fetch all steps | | `--save` | Option | — | Save output as JSON file | ```bash # Get image metric at step 0 swanlab api run medias my-team/image-classification/abc123 --keys generated_image # Get all audio steps swanlab api run medias my-team/image-classification/abc123 --keys audio --all ``` ### run histograms Get histogram (parameter distribution) metrics for an experiment. Each point is a distribution snapshot at one step: `values` holds per-bin counts, `bins` holds the corresponding `N+1` bin edges, and the x axis is always `step`. ```bash swanlab api run histograms --keys [OPTIONS] ``` | Argument/Option | Type | Default | Description | | -------------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `path` | Positional | Required | Experiment path | | `--keys` | `str` | Required | Comma-separated histogram keys, e.g. `"grad,weight"` | | `--sample` / `-s` | `int` | `1500` | Max snapshots per key (max 1500), downsampled by the server over steps | | `--range-start` | `float` | `None` | Lower bound (inclusive), must be an integer value (fractional values raise an error); `0` or omitted means unbounded | | `--range-end` | `float` | `None` | Upper bound (inclusive), must be an integer value (fractional values raise an error); `0` or omitted means unbounded | | `--ignore-timestamp` | Flag | `False` | Remove timestamp field | | `--save` | Option | — | Save output as JSON file | **Notes:** * Histograms only return server-side samples by step — each key returns at most `sample` snapshots. Full export and aggregate statistics are not supported yet ```bash # Get the grad histogram (up to 1500 snapshots by default) swanlab api run histograms my-team/image-classification/abc123 --keys grad # Multiple keys, up to 500 snapshots each swanlab api run histograms my-team/image-classification/abc123 --keys grad,weight -s 500 # Only snapshots with step in [0, 500] swanlab api run histograms my-team/image-classification/abc123 \ --keys grad --range-start 0 --range-end 500 ``` ### run logs Get console logs for an experiment. ```bash swanlab api run logs [OPTIONS] ``` | Argument/Option | Type | Default | Description | | -------------------- | ---------- | -------- | ------------------------------------------- | | `path` | Positional | Required | Experiment path | | `--offset` / `-o` | `int` | `0` | Log shard index | | `--level` / `-l` | `str` | `"INFO"` | Log level: `DEBUG`, `INFO`, `WARN`, `ERROR` | | `--ignore-timestamp` | Flag | `False` | Remove timestamp field | | `--save` | Option | — | Save output as JSON file | ```bash # Get INFO level logs swanlab api run logs my-team/image-classification/abc123 # Get WARN and above swanlab api run logs my-team/image-classification/abc123 --level WARN # Get specific shard swanlab api run logs my-team/image-classification/abc123 --offset 1 ``` ### run export-logs Export experiment logs as a downloadable `.log` file. ```bash swanlab api run export-logs [OPTIONS] ``` | Argument/Option | Type | Default | Description | | --------------- | ---------- | -------- | ------------------------------------------------ | | `path` | Positional | Required | Experiment path | | `--start` | `int` | `0` | Start row index (0-based) | | `--rows` / `-r` | `int` | `500000` | Number of rows to export, max 500000 | | `--save` | Option | — | Save output as JSON file (includes download URL) | ```bash # Export first 10000 rows swanlab api run export-logs my-team/image-classification/abc123 --rows 10000 ``` ### user info Get current logged-in user information. ```bash swanlab api user info [OPTIONS] ``` | Option | Description | | -------- | ------------------------ | | `--save` | Save output as JSON file | ```bash swanlab api user info ``` ### self-hosted info Get self-hosted instance information. ```bash swanlab api self-hosted info [OPTIONS] ``` | Option | Description | | -------- | ------------------------ | | `--save` | Save output as JSON file | ```bash swanlab api self-hosted info ``` ### self-hosted create-user Create a new user in the self-hosted instance (super admin only). ```bash swanlab api self-hosted create-user [OPTIONS] ``` | Option | Type | Description | | ------------------- | ------ | --------------------------- | | `-u` / `--username` | `str` | Required, new username | | `-p` / `--password` | `str` | Required, new user password | | `--save` | Option | Save output as JSON file | ```bash swanlab api self-hosted create-user -u testuser -p test123456 ``` ### self-hosted list-users List all users in the self-hosted instance (super admin only). ```bash swanlab api self-hosted list-users [OPTIONS] ``` | Option | Type | Default | Description | | -------------------- | ------ | ------- | ------------------------------ | | `--page_num` / `-n` | `int` | `1` | Page number | | `--page_size` / `-s` | `int` | `20` | Page size | | `--all` | Flag | `False` | Auto-paginate, fetch all users | | `--save` | Option | — | Save output as JSON file | ```bash # List all users swanlab api self-hosted list-users --all ``` ### self-hosted list-projects List all projects in the self-hosted instance (super admin only). ```bash swanlab api self-hosted list-projects [OPTIONS] ``` | Option | Type | Default | Description | | -------------------- | ------ | ------- | --------------------------------- | | `--page_num` / `-n` | `int` | `1` | Page number | | `--page_size` / `-s` | `int` | `20` | Page size | | `--all` | Flag | `False` | Auto-paginate, fetch all projects | | `--search` | `str` | `None` | Search keyword | | `--creator` | `str` | `None` | Filter by creator username | | `--workspace` | `str` | `None` | Filter by workspace username | | `--save` | Option | — | Save output as JSON file | ```bash # List all projects swanlab api self-hosted list-projects --all # Search for projects swanlab api self-hosted list-projects --search image --all ``` ### self-hosted summary Get system usage summary for the self-hosted instance (super admin only). ```bash swanlab api self-hosted summary [OPTIONS] ``` | Option | Description | | -------- | ------------------------ | | `--save` | Save output as JSON file | ```bash swanlab api self-hosted summary ``` ### self-hosted list-workspaces List all workspaces in the self-hosted instance (super admin only). ```bash swanlab api self-hosted list-workspaces [OPTIONS] ``` | Option | Type | Default | Description | | -------------------- | ------ | ------- | ----------------------------------- | | `--page_num` / `-n` | `int` | `1` | Page number | | `--page_size` / `-s` | `int` | `20` | Page size | | `--all` | Flag | `False` | Auto-paginate, fetch all workspaces | | `--search` | `str` | `None` | Search keyword | | `--save` | Option | — | Save output as JSON file | ```bash # List all workspaces swanlab api self-hosted list-workspaces --all ```