list_jobs

Cost: Free (0 credits).

list_jobs lists your recent background jobs — the crawls and Search Console pulls that run in the background — newest first, each with its job_id. It is the tool to reach for when you do not have a job_id to hand. The reply says how many jobs you have in total and how many it did not show, so a cut list never reads as your whole history.

What it does

Reads your own jobs, scoped to your account, and returns one line each: which tool ran, what state it is in, when it was created and finished, which of your sites it ran against, and the job_id to ask about. The site is named by DOMAIN; a job with no project scope says so, and a project you have since removed falls back to the id it was recorded with.

A job whose stored stamps contradict each other — a finished earlier than its created — is marked timestamps out of order rather than printed as an ordinary timeline. Both stamps are still shown, because both are real: some rows were written with created_at stamped at insert time, after the work they record. No duration is derived from such a pair; a contradiction does not describe a short run, it describes an unknown one, and get_job_status makes the same refusal.

What the list shows, and what needs a second call

The list deliberately carries no results. A finished crawl or Search Console pull can store a very large result — one measured pull held close to a megabyte — so printing even a few of them would bury the answer you asked for.

Take a job_id from the list and pass it to get_job_status for that one job's detail: its crawl summary, how far a running job has got, or why it failed.

Narrowing the list, and reading past the first page

Pass status to see only the jobs in one state — queued, running, succeeded or failed — and project_id to see only the ones that ran against a single site. The two combine, so "the failed crawls for this domain" is one call. A status the jobs table cannot hold is refused rather than quietly ignored.

A narrowed reply says so. The heading names the filter it applied — your 3 most recent failed job(s) of 3 for example.com — and the count is of the filtered set rather than of your whole history, so a short list is never read as "this is everything". When nothing matches, the reply names what you asked for (No failed job(s) for example.com found) and points at the call that drops the filter, instead of telling you that you have never run a job.

The list is capped, and the reply says how many jobs it did not show along with the before_id to pass for the next page. Each page names the next value, so a busy account can be read all the way down; page two calls itself a continuation and counts what remains past the cursor. A before_id that names no job of yours is refused outright — never treated as "start from the top" — while reaching your oldest job says the history ends there.

Example

Ask your MCP client in plain language:

How is the crawl I started doing?

The tool replies with your recent jobs; pick the one you mean and ask get_job_status about its job_id.

Input

Returns

One line per job — tool, status, timestamps, which of your sites it ran against, and job_id — newest first, followed by a pointer to get_job_status for the full result, and the before_id for the next page when the list was cut. When status or project_id narrowed the list, the heading names the filter and the count is of the filtered set; when nothing matched, the reply names the filter rather than reporting an empty account. Guidance to the two tools that create jobs when you have run none.