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": ...}; 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 job exits 0 whatever the job's status, and prints the whole job while it has no result. With --wait, a failed or cancelled job exits 1. For a large parse, it fetches the full content as in Large documents and workbooks.
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. Each event has sequence, at and status, plus progress (units_done, units_total, stage and so on) and message when the job has them. The first event is the job's state as it is now.
| Flag | What it does |
|---|---|
--last-event-id ID | Resume after a dropped stream: pass the last event's sequence. The new stream starts from the job's current state and keeps numbering after ID. |
The stream is a convenience for showing progress, and it counts against your per-minute limit: read the outcome with nace job.
Cancel a job
nace cancel <id> cancels a running job and drops any job, finished or not, from nace jobs. The job stays readable with nace job. A cancelled job is not charged unless results were already delivered before the cancel; a finished one keeps its charge. Stderr says cancelled <id>; stdout stays empty.