List background jobs (free)
codex_job_listList a workspace's background jobs newest first to recover job IDs lost after context compaction or interruption; filter by status or limit results.
Instructions
Deprecated: use amicus_job_list. 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. On an active call it selects where Codex works, not what it can read — it is not a read boundary. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes |