Skip to content

job ls

List jobs in Studio.

Synopsis

usage: datachain job ls [-h] [-v] [-q] [--status STATUS] [--team TEAM] [--limit LIMIT] [--json] [-e]

Description

This command lists jobs in Studio. You can filter jobs by their status, specify a team, and limit the number of jobs returned. By default, it shows the 20 most recent jobs.

Every job shows its ID, name, status, creation time, start time and author. The start time is when a worker claimed the job, and - means no worker claimed it. --extended adds the compute cluster it ran on and a breakdown of its stages - see Extended output.

Options

  • --status STATUS - Status to filter jobs by
  • --team TEAM - Team to list jobs for (default: from config)
  • --limit LIMIT - Limit the number of jobs returned (default: 20)
  • --json - Print the job list as JSON
  • -e, --extended - Show extra job details
  • -h, --help - Show the help message and exit
  • -v, --verbose - Be verbose
  • -q, --quiet - Be quiet

Extended output

--extended adds two columns:

Column Meaning
Cluster The compute cluster the job ran on. datachain job clusters shows what that cluster is - its region, machine and capacity
Stages How long the job spent in each stage 
+--------------------------------------+--------+----------+----------------------+----------------------+--------------+--------------+---------------------------------+
| ID                                   | Name   | Status   | Created at           | Started at           | Created by   | Cluster      | Stages                          |
+======================================+========+==========+======================+======================+==============+==============+=================================+
| 0502eef6-a32e-45fa-8e3b-d20ec0abbcf0 | daily  | COMPLETE | 2026-09-16T00:00:00Z | 2026-09-16T00:00:04Z | alice        | prod-cluster | Waiting in queue: 4s            |
|                                      |        |          |                      |                      |              |              | Downloading files: 1h 5m        |
|                                      |        |          |                      |                      |              |              | Installing dependencies: 2m 30s |
|                                      |        |          |                      |                      |              |              | Running query: 12m 26s          |
+--------------------------------------+--------+----------+----------------------+----------------------+--------------+--------------+---------------------------------+

A job passes through some of: waiting in queue, requesting workers, preparation, installing dependencies, downloading files, waking up the data warehouse, and running the query. A stage still going reads running, and one whose timing is unavailable reads - - never 0s.

Comparing time queued against time running the query is how you tell a slow job from one that sat waiting for a worker.

JSON output

--json returns the full job details as JSON. Add --extended for stage timestamps; --status, --limit and --team still apply.

datachain job ls --json --extended --status failed

Match a job to a cluster on compute_cluster_id, not on the cluster's name. A retired cluster keeps its jobs but no longer appears in datachain job clusters, and a later cluster can take its name, so matching on the name can attribute a job to a machine it never ran on.

Status options

You will be able to filter the job with following status:

  • CREATED - Job has been created but not yet scheduled
  • SCHEDULED - Job is scheduled to run at a future time
  • QUEUED - Job is in the queue waiting to be executed
  • INIT - Job is initializing and preparing to run
  • RUNNING - Job is currently executing
  • COMPLETE - Job has finished successfully
  • FAILED - Job has failed during execution
  • CANCELING_SCHEDULED - A scheduled job is being canceled
  • CANCELING - A running job is being canceled
  • CANCELED - Job has been canceled
  • ACTIVE - Job is in active state.
  • INACTIVE - Job is in inactive state.

Note: The following statuses are considered active jobs:

  • CREATED
  • SCHEDULED
  • QUEUED
  • INIT
  • RUNNING
  • CANCELING_SCHEDULED
  • CANCELING

Examples

  1. List all jobs (default limit of 20): 

    datachain job ls

  2. List jobs for a specific team: 

    datachain job ls --team my-team

  3. List jobs with a specific status: 

    datachain job ls --status complete

  4. List more jobs by increasing the limit: 

    datachain job ls --limit 50

  5. List jobs with verbose output: 

    datachain job ls -v

  6. List jobs with extra details, including the compute cluster they ran on: 

    datachain job ls --extended

Notes

  • The default limit of 20 jobs helps manage the output size and performance
  • Jobs are typically listed in reverse chronological order (newest first)
  • Use the --status filter to find jobs in specific states (e.g., running, completed, failed)
  • --extended asks for more, so plain job ls stays the quicker way to check what is running
  • datachain job logs shows a job's output