List background jobs (free)
codex_job_listList background Codex jobs for a workspace, newest first, to recover job IDs lost during interruptions. Review each job's status, outcome, and expiry for quick triage.
Instructions
List the background jobs known for this workspace, newest first.
Free — no model call. Use to recover job_ids lost across context compaction or
interruption. Returns each job's id, kind, status, start time, result_available,
result_ok (a done job's outcome — true/false/null; see codex_job_status), and expiry,
so a stored failure is triageable without fetching each result.
Returns every retained job by default; pass limit (1-1000) or status to narrow. They
narrow independently — omitting limit returns every job matching status, not every
job. Only an explicit limit truncates: when more jobs match, the response sets
truncated: true with a truncation_hint — the extra rows are dropped, not paged, so
omit limit to get them all rather than looking for a cursor.
Read a job's result promptly — a finished record can silently drop off. This list is
not permanent storage: terminal records expire after the TTL (default 24h), and a
per-workspace soft cap (default 50, clamped 1-1000) evicts the oldest terminal records
as new jobs start, so a finished job can disappear even before its expires_at.
Running jobs are never evicted, so a busy workspace can hold more than the cap — and
more than limit's 1000 ceiling.
Includes sync-originated records (any sync consult/review/delegate call); the cap/TTL
eviction covers both.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum jobs to return, newest first (1-1000). Omit (or pass null) to return every retained job that matches — the default; it caps nothing, and does not override `status`. Only an explicit limit truncates: then the response sets truncated=true and the extra rows are dropped. | |
| status | No | Return only jobs in this lifecycle state ('running', 'done', 'failed', 'cancelled', 'timeout'); omit for all states. | |
| workspace_root | No | Absolute path to the target repo root — pass it (or an MCP root) to target the intended repo; otherwise the call falls back to the server's own cwd and sets meta.workspace_warning. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes |