Perception
Job files
A result links the job's own files: full Markdown, figure crops, ground crops, transcripts, converted PDFs, cell maps and spreadsheet rows. See Files a job produced.
- Per-minute limit: downloading files doesn't count against it. Reading the request (
nace job-request) and the event stream (nace events) use the independent job-read window, separate from creates. - Expiry: results and their files stay until explicit deletion. After that, a command on a file fails with
404or410 result_expiredand exits1.nace jobstill reads the job, without its result.
Download a file
nace file <id> <document.content_url> # a very large document's full Markdown, saved as <id>.md
nace file <id> parse-images/<ref> --save figure-1.png
nace file <id> request --save - # to stdout
nace file <id> ground-crops/<ref> --link # a five-minute signed linknace file <id> PATH downloads one of the job's files.
PATHis a link from the job's result, or the part after the job id, such asparse-images/<ref>. A query or fragment in it is ignored.- Other paths: a path such as
.., or a full link from another job's result, exits2. document.content_urlis on a parse result only when its Markdown is too large to return whole. See Very large results.
| Flag | What it does |
|---|---|
--save PATH | Where to write the file; - for stdout. An existing file is replaced. |
--link | Print a stored file's signed link instead. It works for five minutes, without your API key. With --json, print {"url": ..., "expires_at": ...}. |
--wait-timeout SECONDS | How long to wait for content the document service is still preparing (default 600). Past it, the command exits 1: run it again later. |
Where the file goes
Without --save, the file goes in the current directory, as <id>.md for a document's full Markdown, else <id>-<kind>[-<digest>] plus the kind's extension, if it has one. Stderr then says saved <path>.
<kind>is the path's first segment, such asparse-images.<digest>is the first 8 hex characters of the SHA-256 of the rest of the path. It keeps files of one kind apart.- No digest: a path with nothing after its kind gets none:
requestsaves as<id>-request.json, andeventsas<id>-events.
| Kind | Extension |
|---|---|
document-content, spreadsheet-content | .md |
parse-images, ground-crops | .png |
converted-pdf | .pdf |
parse-transcript, ground-transcript, spreadsheet-cell-maps, spreadsheet-rows, request | .json |
How each file comes
| Files | How they come | With --link |
|---|---|---|
| Stored files: figure crops, ground crops, transcripts, converted PDFs and cell maps | Through their signed link, without your API key. | Prints that link. |
| Everything else: full Markdown, rows, the request and events | Streamed from Drex. | Exits 2, and says to drop --link. |
When it fails
| What happened | Exit code |
|---|---|
| The content's preparation failed. | 1, with a 409. |
The content is still being prepared after --wait-timeout. | 1. Run it again later. |
nace file can't write the file: the --save path isn't writable, or neither is the current directory. | 2, with nothing on stdout. |
PATH is ..-style, or a link from another job's result. | 2. |
Job request
nace job-request <id> prints the whole request the job ran under as JSON: request_type (the operation), source as the document service stored it, and the options, schema, classes or targets. A PDF password is never returned. It counts against the independent job-read per-minute window, separate from creates and expires with the job's result; after that, the command fails with 410 result_expired and exits 1. The output is JSON with or without --json.
Spreadsheet rows
nace rows <id> <rows_url> --all > sheet.tsv
nace rows <id> <rows_url> --start-row 100 --limit 50 --jsonPATH is a sheet's rows_url from the parse result (only Parquet sources have one), or the part after the job id (spreadsheet-rows/<ref>). Stdout gets TSV: a line of column names, then one line per row. A cell's tabs, newlines, carriage returns and backslashes are written as \t, \n, \r and \\. Stderr says which rows you got, such as rows 0-49 of 1200; more: --start-row 50 (or --all).
| Flag | What it does |
|---|---|
--start-row N | The first row, numbered from 0 (default 0). |
--limit N | Rows per page, 1 to 100 (default 50). |
--all | Every row from --start-row on, in pages of --limit (default 100). |
--json | Print the page instead: path, start_row, limit, total_rows, columns (each with name and data_type) and rows (each keyed by column name). With --all, print {"columns": [...], "rows": [...], "total_rows": N}. |
A negative --start-row or a --limit outside 1 to 100 exits 2.