Skip to main content
synth-ai status is the read-only control panel for your Synth account. It exposes the same APIs that drive the dashboard—jobs, models, files, RL runs—and returns JSON by default so scripts, agents, and notebooks can consume the data directly.
Tip: The CLI registers both synth-ai status … and top-level aliases (synth-ai jobs …, synth-ai models …, etc.). The subcommands documented below work with either prefix.

​
Quick Reference

CommandPurpose
status summaryOne-shot dashboard of recent jobs, models, and files
status jobs …List, inspect, stream logs, or cancel training jobs
status models …Enumerate SFT/RL models or inspect a specific model
status files …Browse uploaded datasets and artifacts
status runs …Review RL rollouts associated with a job
 
uvx synth-ai status --help          # top-level help
uvx synth-ai status jobs --help     # group help
uvx synth-ai status jobs list --help  # subcommand help

​
Shared Options

Every subcommand accepts these flags (defined in synth_ai.cli.commands.status.utils.common_options):
  • --base-url URL – Override the Synth backend (defaults come from your environment).
  • --api-key KEY – Use a specific API key instead of the resolved default.
  • --timeout SECONDS – HTTP timeout (default 30 seconds).
  • --json – Where available, emit the raw JSON response instead of tables.
Credentials usually come from synth-ai setup, but you can combine --base-url and --api-key for cross-org or staging queries.

​
Dashboard Snapshot (status summary)

uvx synth-ai status summary --limit 5
The summary command fetches the latest jobs, models, and files in parallel and renders them in Rich tables. Use it as a read-only health check or a quick LLM context bundle.
  • --limit (default 5) controls the number of rows per resource.
  • Pass --json to receive a payload with jobs, models, and files arrays.

​
Jobs Command Suite

The jobs group is defined in synth_ai.cli.commands.status.subcommands.jobs. It provides deep inspection tools for both SFT and RL workflows.

​
List jobs

uvx synth-ai status jobs list \
  --status running \
  --type rl_online \
  --created-after 24h \
  --limit 20
Options (CLI defaults from the code):
  • --status {queued,running,succeeded,failed,cancelled}
  • --type {sft_offline,sft_online,rl_online,dpo,sft}
  • --created-after VALUE – accepts ISO timestamps or relative offsets (5m, 2h, 7d).
  • --limit N – default 20.
  • --json – emit raw job objects.

​
Job detail commands

CommandDescriptionNotes
get <job_id>Fetch full job metadata (StatusAPIClient.get_job).Combine with --json for automation.
history <job_id>List recorded runs/episodes for a job.Renders as a table; JSON available.
timeline <job_id>View temporal events (queue, start, finish, errors).Useful for RCA and SLAs.
metrics <job_id>Render tracked metrics (loss curves, reward stats).Pair with --json to feed dashboards.
config <job_id>Echo the submitted training payload.Great for debugging config drift.
status <job_id>Print the current lifecycle state.Lightweight check for scripts.
logs <job_id>Stream job events; supports --since, --tail, --follow.Follows until interrupted when --follow is set.
cancel <job_id>Request job cancellation.Requires appropriate org permissions.
Example: tail the latest events and keep following. 
uvx synth-ai status jobs logs rl_job_123 \
  --since 1h \
  --tail 200 \
  --follow

​
Models

Backed by StatusAPIClient.list_models / get_model. 
uvx synth-ai status models list --type sft --limit 50
uvx synth-ai status models get ft:org:example --json
  • --type accepts rl or sft.
  • --limit defaults to 20 when omitted.
  • --json returns the raw model object (via rich.JSON if omitted).

​
Files

Inspect uploaded datasets and artifacts (StatusAPIClient.list_files, get_file). 
uvx synth-ai status files list --limit 50
uvx synth-ai status files get file_abc123 --json
Use this to verify dataset uploads before launching a training run or to pull metadata for auditing.

​
RL Runs

The runs group surfaces RL rollout records (StatusAPIClient.list_job_runs) and the events emitted within a specific run. 
uvx synth-ai status runs list rl_job_123
uvx synth-ai status runs logs rl_job_123 --run 42 --json
  • runs list requires the job ID and returns every known run (typically ordered newest-first).
  • runs logs targets a single run via --run RUN_ID and accepts --since for relative/absolute filtering. Output is an events panel or raw JSON.

​
JSON-first Workflows

All responses are JSON serializable, making the commands agent-friendly: 
uvx synth-ai status jobs list --status succeeded --json \
  | jq -r '.[].id'

uvx synth-ai status jobs metrics rl_job_123 --json \
  | jq '.metrics.train_loss[-1]'

uvx synth-ai status models get ft:org:example --json \
  | jq '.backing_model'

​
Automation Notes

  • Run uvx synth-ai jobs … as a shorter alias for uvx synth-ai status jobs ….
  • The CLI uses async HTTP clients; long-running commands (e.g., logs --follow) cancel cleanly with Ctrl+C.
  • Combine with uvx synth-ai train --no-poll for automation loops that submit a job and periodically poll status or metrics.

​
Next Steps