In [Jobs & orchestration — multi-task, dependencies, control flow](/lessons/s1-jobs-orchestration/) we built what a Job is — a graph of tasks with dependencies, control flow, and recovery. This lesson is how you drive it without clicking the UI: the REST API and the CLI. The exam quizzes specific endpoints almost verbatim — but one distinction organizes all of them, and once you hold it the endpoints stop being a list to memorise.

The spine

Beat 1 — the anchor: job vs run

Here's the distinction that makes the whole API legible — a name-collision worth pinning:

Anchor. A job is the definition (the tasks, schedule, clusters you configured). A run is one execution of that job (one attempt, with a status: pending/running/success/failed). Every endpoint acts on either the job (the recipe) or a run (one time you cooked it).

Miss this and you reach for the wrong endpoint. Predict which is which:

"Show me the notebooks/tasks configured in this job" — job or run? · "Did last night's execution succeed?" — job or run?

…

The first is a job question (the recipe). The second is a run question (one cooking). That reflex picks the endpoint every time.

Lock it. job = definition, run = one execution. Every endpoint is a verb on one or the other.

The dials (skim now; return when a question needs one)

◆ The endpoints that get tested (Jobs API 2.2)

On the job (the definition):

GET  /api/2.2/jobs/get?job_id=123     -- the job's full config: tasks, notebooks, clusters
GET  /api/2.2/jobs/list               -- all jobs in the workspace
POST /api/2.2/jobs/create             -- define a new job (external systems create jobs dynamically)
POST /api/2.2/jobs/run-now            -- trigger a run of an existing job

On runs (executions):

GET  /api/2.2/jobs/runs/list?job_id=123   -- every run of a job, with status → "check the statuses of all runs"
GET  /api/2.2/jobs/runs/get?run_id=456    -- one run in detail
POST /api/2.2/jobs/runs/repair            -- repair a failed run (reruns failed + downstream tasks)

Two tells that hang off the anchor:

• "Review the notebooks/tasks configured in a job" → jobs/get (a job-definition question), not a runs endpoint.
• "Retrieve all runs of a job to check their statuses" → jobs/runs/list (a run question).

And recall from [Jobs & orchestration — multi-task, dependencies, control flow](/lessons/s1-jobs-orchestration/): runs/repair reruns only the failed task and its downstream dependents — the API form of "repair-run beats run-now." run-now starts a whole fresh run.

◆ What changed in 2.2 (the freshness point)

Jobs API 2.2 added pagination: list fields like tasks, job_clusters, parameters, environments are capped at 100 elements per response; if there are more, the response carries a next_page_token you pass back as page_token. The old has_more boolean was removed — detect "more results" by whether a next_page_token is present. So a 150-task job's jobs/get returns the first 100 + a token. "How do you page through a large job's tasks?" → next_page_token, not has_more. (2.1 is the older version still seen in questions; the verb is what matters, not the version number.)

◆ The four ways to drive a Job (the landscape)

• UI — clicking; fine for exploring, not repeatable.
• DABs/YAML — the job defined as code, version-controlled in Git. Standard for production ([Declarative Automation Bundles — deploying Databricks as code](/lessons/s9-dabs-deploy/)).
• REST API — for external systems to create/trigger/inspect jobs programmatically.
• CLI — databricks jobs … for ad-hoc work and debugging.

databricks jobs list                       # → GET jobs/list
databricks jobs get   --job-id 123         # → GET jobs/get
databricks jobs run-now --job-id 123       # → POST jobs/run-now
databricks jobs list-runs --job-id 123     # → runs/list

The CLI mirrors the API. But for running a bundle-defined job in a target environment you use databricks bundle run <job_key> -t <target> — the DABs path ([Declarative Automation Bundles — deploying Databricks as code](/lessons/s9-dabs-deploy/)), which respects the target's config instead of hitting the raw job by id.

Takeaways (rebuild it from these)

1. Job = definition; run = one execution. Every endpoint acts on one or the other — that's how you pick it.
2. Job endpoints: jobs/get (config/tasks → "review the notebooks in a job"), jobs/list, jobs/create, jobs/run-now. Run endpoints: jobs/runs/list ("check run statuses"), jobs/runs/get, jobs/runs/repair (rerun failed+downstream).
3. API 2.2 paginates large list-fields via next_page_token (100/page; has_more removed).
4. Four ways to drive a Job: UI (explore), DABs/YAML (production, versioned), REST (external integration), CLI (ad-hoc). CLI mirrors the API; bundle jobs run via databricks bundle run.

Before you move on — say these without scrolling up

1. "Review the tasks configured in a job" vs "check the statuses of all runs" — which endpoint each, and why?
2. A job has 150 tasks — how do you page past the first 100 in API 2.2?
3. Four ways to drive a Job — which is the production standard?

Next: the compute those jobs run on, and the Spark knobs that decide whether they're fast or spill → [Job & environment configuration — compute and Spark tuning](/lessons/s1-job-env-config/).