Perception
Jobs
Reading, listing and cancelling jobs is free and works at any balance. See Jobs and results.
List jobs
nace jobs --operation parse --status succeeded --limit 50
nace jobs --all --json > jobs.jsonStdout gets jobs (<n>):, the number of jobs printed, then one line per job, newest first, indented two spaces: its status, operation and id, as succeeded parse <job_id>, then its name when it has one. When more pages follow, the last line is next: <cursor>: pass it as --cursor.
| Flag | What it does |
|---|---|
--operation {parse,split,classify,extract,ground} | Only jobs of one operation. |
--status {queued,running,succeeded,failed,cancelled} | Only jobs in one status, as Drex last recorded it. A job whose status has changed since is left off the page, so a page can hold fewer than --limit jobs, or none, while more pages follow. |
--limit N | Jobs per page, 1 to 50 (default 20). A larger number exits 2. |
--cursor CURSOR | Start at this page: the next_cursor of the page before. |
--all | Every job, across every page. Not with --cursor; --limit doesn't apply. |
--json | Print {"items": [...], "next_cursor": ...}, each item a job with its job_id; next_cursor is null with --all. |
With --json, the cursor is the next_cursor field. With --status, a page can come back empty while later pages still match: it prints jobs (0):, then next: <cursor>.
Read a job
nace job <id> # the job as it is now
nace job <id> --wait -o result # wait for it, then print its result| Flag | What it does |
|---|---|
--wait | Wait until the job finishes, as a tool does. |
--wait-timeout SECONDS | With --wait, how long to wait (default 600). |
--watch | Print progress events to stderr while waiting. Implies --wait. |
-o, --output {auto,md,json,result,payload,id}, --save PATH | As in Waiting and output. They apply with or without --wait. |
- Without
--wait,nace jobexits0whatever the job's status, and prints the whole job while it has no result. - With
--wait, a failed or cancelled job exits1. - For a large parse, it fetches the full content, as in Large documents and workbooks.
- An
ingestionjob that succeeded but failed a file prints as usual, thenerror: <n> of <m> files failed to ingeston stderr, asnace ingestdoes, and exits1. That holds with or without--wait, and in every-o.
Progress events
nace events <id> streams the job's progress events, one JSON object per line on stdout, until the job ends or about five minutes pass. The first event is the job's state as it is now.
| Field | What it holds |
|---|---|
sequence | The event's number. |
at | When it happened. |
status | The job's status. |
progress | units_done, units_total, stage and so on, when the job reports them. |
message | A message, when the job has one. |
| Flag | What it does |
|---|---|
--last-event-id ID | Resume a dropped stream: pass the last event's sequence. The new stream starts with the job's current state and numbers on from ID. |
The stream is for showing progress, and it counts against the independent job-read per-minute window, separate from creates. Read the outcome with nace job.
Cancel a job
nace cancel <id> cancels a running document job or a recorded workspace processing job started directly by your account. Workspace/file deletion jobs and automatically chained child jobs cannot be cancelled through this command (404). Access to read a shared workspace does not let you cancel another account's jobs. Your account keeps control of its own recorded jobs after sharing ends or the workspace is deleted.
- Listing: a document job you cancel, finished or not, drops out of
nace jobs.nace jobstill reads it. - Charges: a job cancelled before completion isn't charged, including parts already delivered. A finished job keeps its charge.
- Output: stderr says
cancelled <id>; stdout stays empty.