--- title: "query_tables" method: POST path: "/v1/workspaces/{workspace_id}/tools/query-tables" tags: ["tools"] --- # query_tables `POST /v1/workspaces/{workspace_id}/tools/query-tables` ## Request - Base URL: `https://ndi-api.nace.ai` (the document declares no server; this is the origin it was published from) - URL: `https://ndi-api.nace.ai/v1/workspaces/{workspace_id}/tools/query-tables` - Auth: API key in header `X-API-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Answer a natural-language question over uploaded table files — one or several. **Cost class: slow.** ``paths`` is a list of selection rows — ``{"path": ...}`` for a whole file, ``{"path": ..., "component": }`` for one tab of one workbook (repeat the path to select several tabs). Every path must be a **table file** — a spreadsheet (xlsx, xls, xlsm, xlsb, ods) or record file (csv, tsv, parquet, jsonl, ndjson, json); a document, media, or image path is refused with ``invalid_request`` naming ``qa-file``. Every tab is askable whatever its ingestion produced: selections whose tabs all have extracted rows are answered by the SQL engine — the answer keeps full result parquet storage outside the response and returns bounded previews plus authenticated workspace result-file citations — while a selection holding tabs with only a rendered sheet is answered by a QA agent that reads renderings and queries row extractions together (no result previews on that lane; citations quote the sheets). ``component`` names are workbook-local — the same strings ``file-metadata`` and ``filtered-search`` publish as ``component``, matched exact-name first, then the unambiguous sanitized alias. A name that matches nothing on its own workbook — or any ``component`` on a single-table upload (csv/jsonl/parquet), which has no named parts — is ``invalid_request``. A selected tab with no usable content at all is reported in ``unavailable`` rather than silently dropped. Execution survives HTTP disconnects. By default the route waits and returns the original answer shape. Send ``Prefer: respond-async`` to return a Job immediately, then poll its ``Location`` URL. ``Idempotency-Key`` recovers the same job after a lost response. Only explicit job cancellation stops it. ## Path parameters - `workspace_id` string, uuid, required: Workspace identifier. ## Headers - `prefer` string, nullable - `Idempotency-Key` string, nullable: Replaying a request with the same key returns the original job with 200, never a second job. The key is kept with the job for replay and never cleared, so it must not contain personal data. ## Request body - QueryTablesRequest: Question over a bounded set of workspace-uploaded table selections. Every row's ``path`` must name a **table file** — a spreadsheet (xlsx, xls, xlsm, xlsb, ods) or record file (csv, tsv, parquet, jsonl, ndjson, json); a document, media, or image path is refused with ``invalid_request`` naming ``qa-file``. Every tab is askable whatever its ingestion produced — extracted rows, a rendered sheet, or both. - `paths` QueryTableSelection[], required - `path` string, required - `component` string, nullable: One tab of this workbook. Omit to select the whole file. Repeat the path in another row to select several tabs. - `query` string, required - `include_citations` boolean - `output_schema` object, nullable: A JSON Schema (Draft 2020-12, object root, local non-recursive `$ref` only, no `pattern`, `patternProperties` or `unevaluated*`) the answer must follow. When set, the agent writes `answer` as JSON text conforming to it, the run checks that and asks the agent to correct a mismatch, and the result carries the parsed value in `structured_answer`. A field the source does not state comes back null, whatever type the schema gives it. Explanation goes to `reasoning` where the result has one, and evidences are unchanged. If the answer still misses the schema, the run succeeds with `answer` as written and `structured_answer` null. Omit for a prose answer. ## Response `200` Successful Response - union - QueryTablesResponse: Answer, provenance, unavailable inputs, and retained result previews. Two lanes fill this shape. An all-queryable selection runs the SQL engine and returns everything: ``tables`` previews, ``result_citations``, and SQL receipts in ``citations``. A selection holding tabs without extracted rows runs a QA agent over the files' rendered sheets and row extractions together — the answer and quoted ``citations`` are filled, while ``tables`` and ``result_citations`` stay empty (no SQL results exist to retain). ``unavailable`` reports selections with no usable content on either lane. ``job_id`` is the durable job row created for this run; retrieve it via ``GET /v1/jobs/{job_id}`` to inspect or replay the stored answer. - `job_id` string, uuid, nullable - `answer` string, required - `structured_answer` unknown - `error` string, nullable - `timed_out` boolean - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - `citations` Evidence[] - `file_id` string, uuid, required - `path` string, required - `locator` union: Where the snippet sits, when the producer located it. None means the citation is component-level: ground the snippet against path (sheet=component for spreadsheets) to place it. - TextRange: A character span in a derivative's text, with the page(s) it falls on. ``pages`` is every page the span overlaps — a chunk that straddles a page marker belongs to both, and a reader handed only the first would miss the part of the span that carries the match. ``page`` is the first of them, kept because most producers and consumers only ever deal in one page. - `kind` 'text_range' - `page` integer, nullable - `pages` integer[] - `char_start` integer, required - `char_end` integer, required - VisualRegion - `kind` 'visual_region' - `page` integer, required - `bbox` unknown[], required - unknown - SpreadsheetRange - `kind` 'spreadsheet_range' - `sheet` string, required - `a1_range` string, required - JsonlRecord - `kind` 'jsonl_record' - `row_offset` integer, required - `column` string, nullable - JsonPointer: An RFC 6901 pointer into a JSON source; an empty string means the root. - `kind` 'json_pointer' - `pointer` string, required - AudioRange - `kind` 'audio_range' - `start_ms` integer, required - `end_ms` integer, required - RowRange: A 0-based inclusive row run on a parquet table. - `kind` 'row_range' - `start_row` integer, required - `end_row` integer, required - `column` string, nullable - `page` integer, nullable: The 1-based page the producer attributed the snippet to when it produced no locator; None when unknown or when the locator already carries the page. - `relevance_score` number, required - `snippet` string, required - `why` string, required: Which retrieval leg matched, or which graph path led here. - `component` string, nullable: Public component of the hit, in the vocabulary file-metadata lists and qa-file/read-file accept as component= (tab name for spreadsheets, section for split documents); None for a single-component file or when attribution is unavailable. - `sql_table` string, nullable: The run-sql table name holding the hit's component as rows (a spreadsheet tab's table, or a document's printed long tables); None when the component is not a table or the producer does not say. - `line_start` integer, nullable: First line (1-based) of the hit in the text read-file returns for path and component; None when the producer did not place the hit in lines. - `line_end` integer, nullable: Last line (1-based, inclusive) of the hit, counted like line_start; None with it. - `result_citations` QueryTableCitation[] - `result_file` QueryTableResultFile, required: A workspace-visible Parquet file retained from a TablesQA query. - `file_id` string, uuid, required - `handle` string, required - `path` string, required - `file_name` string, required - `format` 'parquet', required - `row_count` integer, required - `download_url` string, required - `preview_url` string, required - `download_url_expires_at` string, date-time, required - `source_paths` string[], required - `sql` string, required - `grounding` TableQueryGrounding: One SQL query executed against the caller's tables while answering. The grounding behind a computed evidence: when the agent answers a count/sum/join question it runs a SQL agent over the uploaded tables, and this is the receipt — the query text and a bounded preview of what it returned. Attached to the evidence it grounds rather than published globally, so a computed figure and its computation travel together. ``source_paths`` name uploaded files, resolved server-side through the caller's access gate exactly like ``source_path`` on the evidence itself. - `sql` string, required - `supports_answer` boolean: False for exploratory SQL the tables engine ran but did not mark as part of the answer's calculation trail. - `result_id` string, nullable: Stable identity of the stored query result behind this receipt. Lets the grounding-rows endpoint replay this exact query for matched-row pages beyond the regions' inline runs. - `source_paths` string[]: The uploaded table files this query read — directly, or through a prior result it built on — e.g. 'planning/FS GF Custom.xlsx'. - `row_count` integer: Rows in the query's full result, not in the preview below. - `columns` TableQueryColumn[] - `name` string, required - `data_type` string, required - `rows` object[]: Leading result rows, values rendered as text — a bounded preview, never the full result. - `preview_truncated` boolean: Whether the preview cut rows or columns. - `verified` boolean: True when at least one claim behind this query passed mechanical verification against the source data. Independent of 'regions': a source without an addressable grid verifies but cannot be pointed at, so an empty 'regions' never means unverified. - `regions` union[]: Original-file coordinates for the verified claims whose source file has an addressable grid. - union - SheetQueryRegion: A verified region on a source file with an addressable grid. Coordinates are expressed in the caller's uploaded workbook or CSV, never in the internal parquet derivative. - … - RowRangeQueryRegion: A verified region on a pageable tabular artifact, addressed by row number. A parquet upload stored as-is uses its own row order. A jsonl or parquet derivative uses the queried artifact's row order; ``derivative_path`` names that artifact when it differs from the caller-facing ``source_path``. - … - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Capture-time provenance status behind this query's regions. 'exact': the exact-provenance sidecar proved every row the query read, so its 'provenance'-basis regions are trustworthy (source regions may be broader than the minimal contributing set when grounding_reason carries a 'regions_broad:…' qualifier). 'unavailable': no exact proof could be captured (a legacy result, or a statement shape the capturer cannot instrument) — no 'provenance'-basis regions are attached, never a guessed whole-table span. 'zero_result': the query matched no rows, so there is nothing to ground. None on legacy payloads and on a query with no unclaimed table left to ground. - `grounding_reason` string, nullable: Qualification on grounding_status, when present. Set for 'unavailable' (explains why proof was not possible) and for 'exact' when capture succeeded but the source regions are broader than the minimal contributing set (e.g. 'regions_broad:narrowing_specs_unavailable'). None when grounding is fully exact or absent. - `result_materialization_error` string, nullable - `unavailable` UnavailableTable[] - `path` string, required - `error` string, required - `error_kind` 'conversion_rejected' | 'conversion_failed' | 'profile_rejected' | 'profile_failed', nullable - `tables` QueryTablePreview[] - `path` string, nullable - `handle` string, required - `row_count` integer, required - `columns` QueryTableColumn[] - `name` string, required - `data_type` string, required - `rows` object[] - `preview_truncated` boolean - Job: Every slow method returns one of these (spec 12 §1.4). There is no ``/parse`` + ``/parse_async`` pair: every job-creating route returns ``202`` with a queued job and accepts ``?wait_seconds=``, returning ``200`` with a terminal job if the work finished inside the window. The caller's code path is the same either way — read ``status``. - `job_id` string, uuid, required: Server-minted id. Poll GET /v1/jobs/{job_id} or pass wait_seconds on create. - `kind` 'parse' | 'split' | 'classify' | 'categorize' | 'extract' | 'ground' | 'ingestion' | 'reconciliation' | 'kg_build' | 'file_upload' | 'file_replace' | 'upload_session_complete' | 'file_delete' | 'files_delete' | 'workspace_delete' | 'intelligent_search' | 'folder_metadata' | 'file_metadata' | 'read_file' | 'hybrid_search' | 'grep' | 'run_sql' | 'locate' | 'qa_file' | 'qa_tables' | 'filtered_search' | 'je_testing' | 'je_testing_v2' | 'deep_search_v2' | 'automatic_agent' | 'ledger_understanding' | 'ledger_understanding_reset' | 'ledger_parse_exhibits' | 'tenant_purge' | 'storage_connection_validate', required: What a job is doing. Open enum — a new member is additive. - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required: ``cancelled`` is a first-class terminal status, not a ``failed`` variant. Conflating them makes error-rate metrics lie and forces every client to string-match an error code. - `name` string, nullable: Display name (the console's 'project'). Public Parse, Split, Classify, Extract, and Ground runs supply a stable server default when blank; citation-generated Ground jobs are excluded. mutable via PATCH /v1/jobs/{job_id}. - `project_id` string, uuid, nullable: Caller-minted grouping id shared by jobs submitted together. Filterable on GET /v1/jobs. - `workspace_id` string, uuid, nullable: The workspace this job reads. Null for a document operation whose source is an upload, a URL, or a prior parse result. - `idempotency_key` string, nullable: Key that was replayed to return this job. Absent when the create call had no Idempotency-Key. - `force` boolean, nullable: The request's own `force` flag, echoed regardless of outcome. Present for kinds whose request carries one (e.g. kg_build, where a true value cleared the durable store before the job ran) so a caller can tell that apart from a build that failed leaving the prior store untouched — `result` alone cannot, since it is absent on failure either way. - `source` union: What this job read, for the document operations that take a single `source` (parse, split, classify, extract, ground); null for every other kind. Together with `workspace_id` this is what lets a caller re-open the document a past run was about — both `workspace_file` and `upload` sources remain until explicit deletion. Read from the stored request, so it rides the same retention path as `query` and `result`: null once `result_state` leaves `available`. - UploadSource: Bytes staged through ``POST /v1/uploads``. Retained until explicit deletion, except under Zero retention. - `type` 'upload' - `upload_id` string, uuid, required: Id returned by POST /v1/uploads. Ordinary bytes remain until their consuming jobs or tenant are deleted. - UrlSource: A public or presigned HTTPS location we fetch server-side. - `type` 'url' - `url` string, required: HTTPS URL the service fetches. - `file_name` string, required: Filename to record for the fetched bytes. - WorkspaceFileSource: A file already in a workspace. The single seam between the two contexts: a granular operation may read a workspace file and still write nothing back. The file need **not** be ingested — granular operations read source bytes, not representations. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - ParseResultSource: A prior Parse job whose parsed artifact can be reused by downstream methods. - `type` 'parse_result' - `job_id` string, uuid, required: Succeeded parse job whose artifact should be reused. - `query` string, nullable: The question this job was asked, for the search kinds that carry one (intelligent_search, qa_file, qa_tables, filtered_search); null for every other kind. Read from the stored request, so it rides the same retention path as `result`: null once `result_state` leaves `available`. Narrow by design — the frozen access context never reaches the wire. File scope is summarised separately as `query_scope`. - `query_scope` union: Where this search ran, summarised for history UIs: the whole workspace, one file path, one folder prefix, or a count of files. Null for non-query jobs, filtered-search page continuations, and once `result_state` leaves `available`. Never lists multiple filenames, never the raw request, and never the frozen API-key id. - WorkspaceQueryScope: The question ran against the whole workspace. - `type` 'workspace' - FileQueryScope: The question ran against one workspace-relative file. - `type` 'file' - `path` string, required - PathPrefixQueryScope: The question ran against one folder subtree. - `type` 'path_prefix' - `prefix` string, required - FilesQueryScope: The question ran against several files; only the count is public. - `type` 'files' - `count` integer, required - `effort` string, nullable: How hard this run worked, for the search kinds that carry it. A deep-search job (kind deep_search_v2) created before the effort knob was removed echoes its requested level: 'low', 'medium', or 'high'; newer deep-search jobs, which all run one configuration, read null. An intelligent_search row carries an internal selector instead: 'fast' is fact-search, 'automatic' is automatic-search, and 'deep' (or the legacy 'balanced') is a deep-search or console QA chat job created before the 2026-09 consolidation — those two are not distinguishable by this field. Null for every other kind. Read from the stored request, so it rides the same retention path as `query` and `result`: null once `result_state` leaves `available`. - `surface` 'deep_search' | 'qa' | 'workbook', nullable: Which console history this deep-search job belongs to. `deep_search` is the public route and the Deep Search page; `qa` and `workbook` are the console chat skins over the same agent. It does not pick the implementation. Null for fact-search and every non-deep-search kind. Jobs stored before this field existed echo `deep_search`. Read from the stored payload, so it rides the same retention path as `query`. - `progress` JobProgress: Absent until the job is ``running``. - `units_total` integer, nullable - `units_done` integer - `items_total` integer, nullable: Files, for batch kinds. - `items_done` integer - `items_failed` integer: Quarantined after exhausting retries, for batch kinds. Excluded from items_done. - `stage` string, nullable: Current pipeline stage, for display only. - `knowledge_graph` KnowledgeGraphBuildProgress: Where a ``kg_build`` is, beyond what ``stage`` alone can say. A graph build runs for minutes to hours through a fixed sequence of phases, and ``stage`` names only the current one. Turning that into "how far along" otherwise means hard-coding the build engine's phase order in every client — an order that lives in another package and is free to gain a phase. So the position is reported rather than inferred. The counters are deliberately not a percentage. The phases are wildly unequal (extraction is ~60% of a build, and its per-document cost varies 25x with how dense the documents are), so weighting them is a presentation decision, made against measurements, that belongs to whoever is drawing the bar. - `phase_index` integer, required: 0-based position of the current phase in the build's fixed run order; equals phase_count when done. - `phase_count` integer, required: How many phases a build passes through before it is done. Currently 9. - `countable` boolean, required: Whether items_total/items_done describe this phase. False for the phases that are a single step, which have no unit to count — draw those as indeterminate rather than as a bar stuck at zero. - `documents` integer, nullable: Documents registered from the corpus, once the registering phase has run. - `mentions` integer, nullable: Mentions extracted across the corpus, once the validating phase has run. - `step` string, nullable: The span in flight inside a single-step phase, reported by the running step itself. Null when the phase counts its own units, or before the step has reported one. - `step_done` integer, nullable: Units of `step` finished, when it has countable units. - `step_total` integer, nullable: Units `step` has to get through, when that is known. - `routing` AutomaticSearchRouting - `selected` 'fact' | 'agent' | 'deep' | 'filtered', required: The route the router chose, the one the request's `mode` named, or `fact` when nothing was searched: the workspace had no ingested files, or the query asked for nothing that a document contains. - `final` 'fact' | 'agent' | 'deep' | 'filtered', required: The pipeline that produced the returned output. It differs from `selected` only in `auto` mode, when the router chose fact search, fact search could not settle the question, and the agent answered instead. - `reason` string, required: The router's explanation of its decision, or why no router ran. - `router_model` string, required: The model used to choose the search pipeline; `none` when no router ran. - `router` union: Which router decided, and what it measured: an LLM (its explanation is ``reason``), NaceDM (its probability and decision point), or `requested` when no router ran: the request's `mode` was `fact` or `agent`, or the workspace had no ingested files. Results routed before this field existed read as the LLM. - AutomaticLlmRouter: An LLM chose the route. Its explanation is the routing's ``reason``. - `kind` 'llm' - AutomaticNaceDmRouter: NaceDM, the decision model, chose the route by scoring how likely the query needs the agent. - `kind` 'nacedm' - `p_agent` number, nullable, required: NaceDM's probability that the query needs the investigating agent rather than one fact-search pass; 1 - p_agent is the probability that fact search settles it. Null when the request was too long for NaceDM to score, which routes to the agent. - `decision_point` number, required: The agent runs when ``p_agent`` is at or above this; fact search runs below it. - AutomaticRequestedRouter: No router ran: the request's ``mode`` named the route, or the workspace had no ingested files. - `kind` 'requested' - `router_wall_ms` integer, nullable: Wall time spent selecting the initial route. - `fact_wall_ms` integer, nullable: Wall time spent running fact search, when selected. - `delegated_wall_ms` integer, nullable: Wall time spent preparing and running the native deep or filtered job. - `result` union: Present on succeeded while retained. Also present on a running classify or extract job that already published a progressive result (labels or values). Null while queued, after its content is removed, and once the job, or the job it ran for, is cancelled. - StorageConnectionValidationResult - `result_type` 'storage_connection_validate' - `connection_id` string, uuid, required: Connection whose API and worker access was validated. - `credential_generation` integer, required: Credential generation activated by this validation. - FolderMetadataResult - `result_type` 'folder_metadata' - `output` FolderMetadataResponse, required: Response body for ``folder-metadata``. Counts are filtered by both the caller's access predicate and the requested ``directory`` — the two compose as an intersection, so the view is neither wider than the access gate nor wider than the declared scope. ``file_entries`` lists the visible source files the counts cover (same scope and recursion as the counts), path-sorted, one page at a time (``page_size``); ``files_truncated`` reports a cut page — resume with ``start_after=``, or narrow. Source paths only, never ingestion derivatives. - `directory` string, required: The folder described, relative to the workspace root (`/` is the root). - `overall_files` integer, required: Files in scope that the caller can see: the folder, or its subtree when recursive. - `categories` CategoryCount[], required: File counts per category across the scope. - `name` string, required: Category path as assigned at ingestion, e.g. `contracts/agreement`. - `count` integer, required: Number of files in scope with this category. - `subdirectories` SubdirectorySummary[], required: The folder's immediate subfolders, each summarizing its subtree. - `name` string, required: The subfolder's name; append it to the described folder to descend. - `overall_files` integer, required: Files in the subfolder's whole subtree that the caller can see. - `top_categories` CategoryCount[]: The subtree's most common categories, most files first, capped. - … - `failed_files` integer, nullable: Files in the subtree with ingestion_status=failed; absent when none. - `ingestion_summary` object, required: File counts per ingestion status across the scope. - `files_truncated` boolean, required: True when `file_entries` is one page of a longer listing; resume with `start_after`. - `file_entries` FolderFileEntry[], required: Files in scope, sorted by path, one page at a time. - `path` string, required: Workspace-relative path of the uploaded file — pass it to file-metadata, qa-file or query-tables as is. - `ingestion_status` 'discovered' | 'queued' | 'ingesting' | 'ingested' | 'stale' | 'expired' | 'failed' | 'not_required', required: The only thing that says whether a file is searchable. ``expired`` cannot be derived from the hash pair: retention clears ``ingested_hash``, so an aged-out file and a never-ingested file look identical. They call for different customer actions, so the status carries the distinction the hashes cannot. - `size_bytes` integer, required: Byte size of the uploaded file. - `category` string, nullable: Ledger document category, when classified. - `kind` string, nullable: Ingestion lane (document / table / media), when known. - `uploaded_at` string, date-time, nullable: When this file was first registered (ISO 8601). - `hint` string, nullable: Present only when a call matched nothing: unfiltered, the nearest existing folder and what it holds; filtered, how many files the folder holds and their categories. - `coverage` Coverage, required: What the access gate withheld, in counts and label names only. Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request. - `restricted_candidates` integer - `labels_required` string[]: Which labels would have been needed to see the withheld candidates. - `request_access_hint` string, nullable - `job_id` string, uuid, nullable: The external operation job; absent for commands inside a search job. - FileMetadataResult - `result_type` 'file_metadata' - `output` FileMetadataToolResponse, required: Response body for ``file-metadata`` — what one uploaded file is, without opening it. ``summary`` is the summary of the file's first section or tab, never a concatenation across components (each component carries its own). A file that is not ingested yet answers 200 with its ``ingestion_status`` and no components; a failed one also carries ``ingestion_error``. - `path` string, required: The uploaded file's path relative to the workspace root, as requested. - `file_id` string, uuid, required: The uploaded file's id, as the files endpoints address it. - `kind` string, nullable: Ingestion lane (document / table / media), when known. - `ingestion_status` 'discovered' | 'queued' | 'ingesting' | 'ingested' | 'stale' | 'expired' | 'failed' | 'not_required', required: The only thing that says whether a file is searchable. ``expired`` cannot be derived from the hash pair: retention clears ``ingested_hash``, so an aged-out file and a never-ingested file look identical. They call for different customer actions, so the status carries the distinction the hashes cannot. - `ingestion_error` string, nullable: Why ingestion failed, when the ledger recorded a reason. - `size_bytes` integer, required: Byte size of the uploaded source object. - `category` string, nullable: The file's primary category path, when classified. - `page_count` integer, nullable: Pages in a paged document; absent for other files. - `tab_count` integer, nullable: Tabs in a workbook; absent for other files. - `summary` string: Summary of the file's first section or tab; each component has its own. - `components` union[]: The file's sections, tabs, image or recording, in reading order. - union - … - `figures` FileFigureInfo[]: PDFs: pictures inside the pages (seals, charts, photos, stamps), in page order; with `component`, only those on that component's pages. Empty for other files and for PDFs ingested before figures were recorded. - `name` string, required: `figure p-`. Pass it as qa-file's `component` to ask the vision engine about this figure alone. - `page` integer, required: 1-based page the figure is on. - `description` string, nullable: What the figure shows, written by a vision model at ingestion; null when not described. - `text` string: Text printed inside the figure, as OCR read it. - `job_id` string, uuid, nullable: The external operation job; absent for commands inside a search job. - ReadFileResult - `result_type` 'read_file' - `output` ReadFileResponse, required: Response body for ``read-file``. A file with several components (a spreadsheet's tabs, a pdf's sections) answers with their text concatenated in the file's own order, each part prefixed by a one-line header naming the component. ``components_returned`` lists what contributed to ``content``; ``components_omitted`` lists components that were cut for size — the character budget ran out, or a part was too large to serve — or that have no text rendering at all (a query-only tab; ask it with ``qa-file``) — so an absent component is always visible, never a silently missing tab. Unnamed components (a recording, a raw upload) are listed by kind. A table a PDF page holds comes as rows — one ``| a | b |`` line each under a header that joins the stacked column headings — the way grep and hybrid-search print it. - `path` string, required - `file_id` string, uuid, required - `content` string, required - `pages_returned` integer[], required - `truncated` boolean, required - `components_returned` string[], required - `components_omitted` string[], required - `sql_tables` string[]: The run-sql names of the tables holding the rows of the long tables printed in the returned sections — count, total or rank those rows there rather than from the text. - `line_start` integer, nullable: First line returned (1-based) when the request named a line range; None otherwise. - `line_end` integer, nullable: Last line returned (inclusive) when the request named a line range; None otherwise or when line_start is past the end of the text. - `line_count` integer, nullable: How many lines the whole selected text has, when the request named a line range; None otherwise. - `table` GrepTable: The table a matching line is a row of, so the row reads without another call. - `first_line` integer, required: Line of the table's first row (its header), in read-file's line numbers. - `last_line` integer, required: Line of the table's last row. - `title` string, nullable, required: The text printed just above the table (its caption, units), clipped; None when there is none. - `header` string, required: The column names: the table's first row, or for an HTML table every header row joined per column with ' > ' (empty when it has none), clipped when very wide. - `rows` integer, nullable: For a table stored as one HTML line (PDF ingestion): how many data rows it has. - `job_id` string, uuid, nullable: The external operation job; absent for commands inside a search job. - HybridSearchResult - `result_type` 'hybrid_search' - `output` SearchResponse, required: Response of ``hybrid-search``. ``candidates_seen`` is the pre-access-filter count so the caller can tell when truncation happened upstream of the access gate. Every ``hits[].path`` is an uploaded **source** path. Each hit also carries the ingestion derivative it was actually read from, but those fields are internal to the host (the agent tools address files that way) and are excluded from this body — a ``/v1`` caller only ever sees the files it uploaded. - `hits` Evidence[], required - `file_id` string, uuid, required - `path` string, required - `locator` union: Where the snippet sits, when the producer located it. None means the citation is component-level: ground the snippet against path (sheet=component for spreadsheets) to place it. - … - `page` integer, nullable: The 1-based page the producer attributed the snippet to when it produced no locator; None when unknown or when the locator already carries the page. - `relevance_score` number, required - `snippet` string, required - `why` string, required: Which retrieval leg matched, or which graph path led here. - `component` string, nullable: Public component of the hit, in the vocabulary file-metadata lists and qa-file/read-file accept as component= (tab name for spreadsheets, section for split documents); None for a single-component file or when attribution is unavailable. - `sql_table` string, nullable: The run-sql table name holding the hit's component as rows (a spreadsheet tab's table, or a document's printed long tables); None when the component is not a table or the producer does not say. - `line_start` integer, nullable: First line (1-based) of the hit in the text read-file returns for path and component; None when the producer did not place the hit in lines. - `line_end` integer, nullable: Last line (1-based, inclusive) of the hit, counted like line_start; None with it. - `candidates_seen` integer, required - `truncated` boolean, required - `coverage` Coverage, required: What the access gate withheld, in counts and label names only. Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request. - `restricted_candidates` integer - `labels_required` string[]: Which labels would have been needed to see the withheld candidates. - `request_access_hint` string, nullable - `job_id` string, uuid, nullable: The external operation job; absent for commands inside a search job. - GrepResult - `result_type` 'grep' - `output` GrepResponse, required: Response of ``grep``. ``files_unscanned`` counts the files that could hold a match but were not read because ``max_matches`` or the scan budget ran out first — narrow with ``path_prefix`` to reach them. - `matches` GrepMatch[], required: The matching lines, in path order then line order. - `file_id` string, uuid, required: The uploaded file the line belongs to. - `path` string, required: Uploaded source path of the file. - `component` string, nullable, required: Public component of the line as file-metadata lists it and read-file accepts as component= (tab name, section); None when the file is the unit (an image, a recording, a raw upload). - `kind` 'section' | 'tab' | 'media' | 'image' | 'raw', required: What the component is: a document section, a spreadsheet tab, an image, a recording, or a raw upload. - `line` integer, nullable, required: 1-based line number in the text read-file returns for path and component (for a single-component file, the same as reading the whole file); document text only. None on a pointer match: a spreadsheet tab (run-sql its sql_table for the answer), an image (its text or summary matched; ask-file reads it), a recording. - `page` integer, nullable, required: The source page the line sits on; None when the text has no pages or the match is a pointer. - `text` string, required: The matching line, clipped around its first match when it is long. - `sql_table` string, nullable: The run-sql table holding the component's rows (a spreadsheet tab, a document's long tables); None when it has none. - `table` GrepTable: The table a matching line is a row of, so the row reads without another call. - … - `context_before` string[]: The `before` lines above the match (document text), clipped, top first. - `context_after` string[]: The `after` lines below the match, clipped. - `files_matched` integer, required: How many of the scanned files had at least one matching line. - `files_scanned` integer, required: How many files were read and matched line by line. - `files_unscanned` integer, required: Files that could match but were not read before the limits ran out. - `truncated` boolean, required: True when max_matches or the scan budget cut the result short. - `mode` 'scan' | 'index', required: scan: every file in scope was read. index: the content index first narrowed the scope to the files holding the pattern's words, and those were read. - `notes` string[]: How the pattern was read, when not as written. - `near_misses` GrepMatch[]: Only when nothing matched: scanned lines holding most of the pattern's words, best first — the document's own wording of what the pattern looked for. - `file_id` string, uuid, required: The uploaded file the line belongs to. - `path` string, required: Uploaded source path of the file. - `component` string, nullable, required: Public component of the line as file-metadata lists it and read-file accepts as component= (tab name, section); None when the file is the unit (an image, a recording, a raw upload). - `kind` 'section' | 'tab' | 'media' | 'image' | 'raw', required: What the component is: a document section, a spreadsheet tab, an image, a recording, or a raw upload. - `line` integer, nullable, required: 1-based line number in the text read-file returns for path and component (for a single-component file, the same as reading the whole file); document text only. None on a pointer match: a spreadsheet tab (run-sql its sql_table for the answer), an image (its text or summary matched; ask-file reads it), a recording. - `page` integer, nullable, required: The source page the line sits on; None when the text has no pages or the match is a pointer. - `text` string, required: The matching line, clipped around its first match when it is long. - `sql_table` string, nullable: The run-sql table holding the component's rows (a spreadsheet tab, a document's long tables); None when it has none. - `table` GrepTable: The table a matching line is a row of, so the row reads without another call. - … - `context_before` string[]: The `before` lines above the match (document text), clipped, top first. - `context_after` string[]: The `after` lines below the match, clipped. - `job_id` string, uuid, nullable: The external operation job; absent for commands inside a search job. - RunSqlResult - `result_type` 'run_sql' - `output` RunSqlResponse, required: One executed statement: shape, bounded preview, and the retained result. The stored result is complete whatever the preview shows; ``result_citation.result_file.download_url`` fetches the whole parquet. ``duplicate`` marks a statement answered from an earlier identical run's stored result — free, and safe to build on. - `sql` string, required: The normalized statement that ran — the result's provenance. - `duplicate` boolean - `result` QueryTablePreview, required: One retained result table with a bounded inline preview. - `path` string, nullable - `handle` string, required - `row_count` integer, required - `columns` QueryTableColumn[] - … - `rows` object[] - … - `preview_truncated` boolean - `source_paths` string[]: The uploaded files the statement read — carried on the response itself so source attribution survives when no result file is materialized (job-attributed agent statements). - `result_citation` QueryTableCitation: Provenance for one generated TablesQA result file. - `result_file` QueryTableResultFile, required: A workspace-visible Parquet file retained from a TablesQA query. - … - `source_paths` string[], required - `sql` string, required - `grounding` TableQueryGrounding: One SQL query executed against the caller's tables while answering. The grounding behind a computed evidence: when the agent answers a count/sum/join question it runs a SQL agent over the uploaded tables, and this is the receipt — the query text and a bounded preview of what it returned. Attached to the evidence it grounds rather than published globally, so a computed figure and its computation travel together. ``source_paths`` name uploaded files, resolved server-side through the caller's access gate exactly like ``source_path`` on the evidence itself. - … - `result_materialization_error` string, nullable - `job_id` string, uuid, nullable: The external operation job; absent for commands inside a search job. - LocateResult - `result_type` 'locate' - `output` LocateResponse, required: Response of ``locate``: the reply NDI's agent reads, and the same findings as fields. - `text` string, required: The reply as NDI's own agent reads it: each piece with the command that reads it and its text (the best pages in full, the rest by their opening lines; every page by its opening lines with `pointer`), then a population's members and the tables to query. - `pages` LocatedPiece[], required: The pieces named, best first. - `path` string, required: Uploaded source path of the file. - `component` string, nullable: The tab or section a read of the piece names; null when the file's text is one. - `paged` boolean, required: True for a page (read it by `number`); false for a window of lines. - `number` integer, required: The page number, or the window's number in a text file. - `line_start` integer, nullable: A window's first line, as read-file numbers lines. - `line_end` integer, nullable: A window's last line, inclusive. - `score` number, required: How likely the piece holds what is needed, 0 to 1. - `head` string, required: The piece's opening text, cut where the reply text cuts it. - `tables` LocatedTableRef[], required: The tables rated for the need, best first. - `sql_table` string, required: The table's name in SQL queries. - `path` string, required: Uploaded source path of the file holding it. - `tab` string, nullable: The workbook tab, when it is one. - `score` number, required: How likely its rows answer the need, 0 to 1. - `columns` string[], required: Every column of the table, in order. - `relevant_columns` string[], required: The columns a query for the need reads, when rated. - `population` LocatedMember[], required: Set when answering needs every file of a kind (each invoice, every contract): the members, best first. - `path` string, required: The file's uploaded source path. - `score` number, required: How likely the file is a member, 0 to 1. - `population_unrated` integer: Files in folders rated likely to hold members that the budget ran out before rating: when above 0, `population` is incomplete; narrow the need to a folder, kind or period and locate again with `every`. - `job_id` string, uuid, nullable: The external operation job. - NdiServiceAppPlatformApiResultsParseResult - `result_type` 'parse' - `file_name` string, required: Source filename recorded for this run. - `lane` string, required: Which parser lane produced this payload, for example document or spreadsheet. - `document` ParseDocument, required: The parsed document payload under ``ParseResult.document``. - `page_count` integer, required: Number of pages (or equivalent sheets) in the parsed source. - `markdown` string, nullable: Markdown rendering when requested in output.formats; null if that format was omitted. - `content_url` string, nullable: Authenticated streaming URL for complete content when markdown contains only a bounded preview. - `text` string, nullable: Plaintext rendering when requested in output.formats; headings and images stripped. - `blocks` ParsedBlock[], nullable: Layout blocks with locations when requested in output.formats; null if omitted. - `id` string, required: Stable id of this layout block within the parsed document. - `type` string, required: Layout role of the block, for example heading, paragraph, table, figure, or signature. A signature block marks where a signature appears; its content is the placeholder [SIGNATURE]. - `content` string, required: Text or caption carried by this block. - `sheet_name` string, nullable: Owning worksheet, including appendix blocks without a cell range. Null for non-spreadsheet blocks. - `source_id` string, nullable: Identity of the embedded image or attachment within this document. - `source_name` string, nullable: Embedded source display name, including nested attachment paths. - `image_anchor` SheetRange: A cell range on a spreadsheet sheet. - … - `markdown_span` TextSpan: A character span in derived text (optional page when known). - … - `table_row_offset` integer: Offset of body rows in the sheet cell map; repeated table header still addresses row index zero. - `location` union: Where this block sits in the source. Null when the parser did not emit geometry. - … - `confidence` number, nullable: Probability, from 0 to 1, that this block's text matches the page, from the OCR review when it ran. Null when the block was not reviewed, or its text changed after review. - `image_url` string, nullable: Crop URL when output.include_images is true and this block is a figure region. - `has_signature` boolean, nullable: True when a signature was detected on any parsed page; the blocks of type signature say where. False only when every parsed page was checked and none was found. Absent or null when signature detection did not run on every parsed page. - `chunks` ParseChunk[]: RAG chunks when chunking.strategy is not none; otherwise empty. - `id` string, required: Stable id of this chunk within the parsed document. - `content` string, required: Chunk text sized for retrieval, not the full document rendering. - `location` union: Where this chunk sits in the source. Null when chunking did not emit geometry. - … - `ocr` ParseOcrData: Optional inline OCR geometry requested by the caller. - `words` OcrElement[]: Word-level OCR elements when output.return_ocr_data is true. - … - `lines` OcrElement[]: Line-level OCR elements when output.return_ocr_data is true. - … - `spreadsheet` ParseSpreadsheet: Spreadsheet-specific Parse artifacts. - `sheets` ParseSpreadsheetSheet[]: Per-sheet cell-map and complete-content URLs when the source was a workbook. - … - `ocr_applied` boolean, required: True when OCR actually ran, regardless of the requested ocr.mode. - `units` integer, required: Measured work units for this parse, typically one per page. The job's `credits` is the final billed amount. - `converted_pdf_url` string, nullable: PDF the office source was converted to before parsing. Block geometry is measured on this PDF. Null when the source was already a PDF or did not need conversion. - `transcript_url` string, nullable: Authenticated job-scoped MediaTimeline JSON for audio/video. Null for non-media and historical jobs. - `transcript` MediaTimeline: Seekable MediaTimeline JSON carried inline on an audio or video parse. - `schema_version` integer, required: Timeline schema version. Current parses emit version 2. - `modality` 'audio' | 'video', required: Whether the source was an audio file or a video file. - `duration_ms` integer, required: Probed duration of the recording in integer milliseconds. - `speakers` MediaSpeaker[]: Diarizer clusters discovered in the recording. Labels stay null unless a caller mapped them. - `id` string, required: Diarizer cluster id for this speaker, for example SPEAKER_00. - `label` string, nullable: Mapped display name when a caller assigned one. Null when only the cluster id is known. - `segments` union[]: Ordered gapless run of speech and silence covering the whole recording. - union - … - `peaks` number[]: Windowed RMS envelope over the full recording, 0..1 inclusive. Empty means measurement unavailable. - `warnings` string[]: Parse settings this run accepted but did not apply, each naming the setting and why, for example a page selection on a file with no pages. Left out when empty. - `disclosures` union[]: Structured signals about how this result was produced. Empty when all behaviours matched what the caller would assume without them. - union - ClassificationGapFillDisclosure: Pages left unclassified by the model were assigned a fallback label. The classification still succeeded. Gap-filled pages should be treated as lower-confidence assignments rather than absences. One disclosure is emitted per distinct fallback label; ``filled_pages`` in that disclosure are exactly the pages that received ``fallback_label``. - … - ClassificationUnreadPagesDisclosure: Pages never entered any model prompt and are therefore unknown. The classification still succeeded. These pages were dropped by the document-size batch or token cap, so no model produced a label for them. They carry the reserved unknown label regardless of unknown_policy and must not be read as gap-fill (the model never saw them). - … - ExtractionNullOnSuccessDisclosure: Schema-required fields returned null because the document did not contain them. The job succeeded. Null means the document was examined and the field was absent — not that extraction failed or was skipped. - … - ParseVendorProvenanceDisclosure: The file was processed by a vendor other than the router's first choice. The parse result is valid. The vendor name is published so a caller can account for differing output quality or formatting between vendors. - … - ParseFidelityDisclosure: An oversized parse used a bounded fidelity mode without dropping extracted text. - … - ContentTruncatedDisclosure: A user-visible content field was truncated before being included in the result. The result is otherwise complete. ``unit`` states how both size fields should be interpreted. - … - SourceIncompleteDisclosure: The source file ended mid-document, so the result covers only the part that arrived. The job succeeded on the bytes that were present, and a lane that can read a partial file still returns everything it could read. Without this disclosure that output is indistinguishable from a complete document, which is the dangerous reading: a short result looks like a short source. No original size is published because an incomplete file carries no record of how long it should have been. ``received_bytes`` is what a caller can compare against the size it believes it sent. - … - SplitResult - `result_type` 'split' - `file_name` string, required: Source filename recorded for this run. - `lane` string, required: Which parser lane produced this payload, for example document or spreadsheet. - `page_count` integer, required: Pages considered while splitting. - `segments` SplitSegment[], required: Ordered packet segments, including unclassified ones when allowed. - `id` string, required: Stable id of this cut within the split result. - `sequence` integer, required: 0-based order of this segment in the packet. - `status` 'matched' | 'unclassified', required: Whether this cut was assigned a class. matched has class (Python SDK: split_class); unclassified was kept because unknown_policy is include. - `class` SplitSegmentCategory - `id` string, required: Stable id of the class this segment was assigned. - `label` string, required: Display name of the assigned class. - `description` string: Caller-supplied description of what belongs in this class. - `parent_id` string, nullable: Parent class id when this assignment is a subclass. - `subcategory_id` string, nullable: Subclass id when the segment matched a nested class. - `classes` SplitSegmentCategory[], nullable: Alternate class assignments when more than one class applied. - `id` string, required: Stable id of the class this segment was assigned. - `label` string, required: Display name of the assigned class. - `description` string: Caller-supplied description of what belongs in this class. - `parent_id` string, nullable: Parent class id when this assignment is a subclass. - `subcategory_id` string, nullable: Subclass id when the segment matched a nested class. - `start_page` integer, nullable: Inclusive first page of this cut. For workbooks, equals sheet_index + 1. - `end_page` integer, nullable: Inclusive last page of this cut. For workbooks, equals start_page. - `sheet_name` string, nullable: Workbook tab for a spreadsheet segment. Null for PDFs. - `json_pointer` string, nullable: JSON Pointer into a structured source when the cut is not a page range. - `instance` SplitInstance - `key` string, required: Instance-key name from the request class, when instance splitting ran. - `value` string, nullable: Extracted instance-key value for this segment. - `classification_confidence` SplitConfidence - `band` 'unavailable' | 'low' | 'medium' | 'high': Coarse confidence band for this split decision. - `score` number, nullable: Numeric score when the runtime produced one. Null otherwise. - `boundary_confidence` SplitConfidence - `band` 'unavailable' | 'low' | 'medium' | 'high': Coarse confidence band for this split decision. - `score` number, nullable: Numeric score when the runtime produced one. Null otherwise. - `content` string, nullable: Segment markdown when output.include_content is true. Null otherwise. - `artifacts` SplitArtifact[]: Downloadable files when output.materialize_files is true. Spreadsheet segments always include a single-sheet XLSX URL even when that flag is false. - `url` string, required: Authenticated URL of a materialized file for this segment. - `warnings` string[]: Non-fatal notes about this segment, such as a forced class assignment. - `units` integer, required: Measured work units for this split. The job's `credits` is the final billed amount. - `warnings` string[]: Parse settings this run accepted but did not apply, each naming the setting and why, for example a page selection on a file with no pages. Left out when empty. - ClassifyResult - `result_type` 'classify' - `reason_status` 'pending' | 'complete' | 'failed' | 'not_requested': Pending means labels are available while the top-label reason is still running. Complete means the top-label reason finished. Failed means labels stand and the top-label reason did not finish. A runner-up reason that does not finish leaves that label empty and does not by itself fail the job. Reasons that finished are kept. Not_requested means include_reason was false. Always read the job status for cancellation or failure. Default complete so stored results from before this field validate unchanged. - `labels_at` string, date-time, nullable: When NDI published this job's labels, as an ISO 8601 UTC timestamp, on the same clock as started_at and finished_at. Time to labels is labels_at minus created_at. Reason time is finished_at minus labels_at. Those gaps mean the same thing on every lane. Null on a cache replay, and when labels and the reason arrived together. - `units` ClassifyUnit[], required: One scored unit per document, or per page when granularity is page. - `granularity` 'document' | 'page': Whether this unit scores the whole document or one page range. - `page_range` ClassifyPageRange - `start` integer, required: First page of this unit, 1-based and inclusive. - `end` integer, required: Last page of this unit, 1-based and inclusive. - `unknown` boolean, required: True when no requested class won this unit — including reserved other and pages never read by any model — regardless of unknown_policy. False when a requested class won, even if some pages were other. - `labels` ClassifyLabel[], required: Ranked class assignments for this unit, best first. - `class_id` string, required: Id of this label. One of the request classes, or the reserved id other when no requested class matched this slice. other can be the top label when the unit is unknown, or a ranked alternative when some pages did not match. Join request classes on this only when the id is in your classes list. - `subclass_id` string, nullable: Subclass id when the assignment is a nested class. Null for a top-level class. - `label` string, required: Display name of that class. Copied from the request for a caller-defined class_id; a freeform name when class_id is other. - `rank` integer, required: 1-based position in this unit's labels after classes are sorted by score. 1 is the assigned (or top) class; later ranks are alternatives kept by output.max_alternatives. - `reason` string, nullable: Short model explanation for this label, only when output.include_reason is true. For the top label, why that class was chosen. For a later rank on an abstained unit, why that class was close but not the pick. - `confidence` number, nullable: DREX's probability for this label, averaged over the menu orders, when DREX decided it. A document label shared by several segments is the page-weighted mean of the probability recorded on each segment, when every label in the unit has one. Labels are ordered by page coverage. Confidence is per label, so a lower rank can carry a higher confidence. An abstained unit's top label is that mean. Its runner-up labels carry DREX's probability for that runner-up option. When any other label in the unit lacks a DREX probability, every such label uses the share of the unit (pages or sheets) assigned that class. Runner-up labels on an abstained unit do not use that share. - `unknown_units` integer: Count of units where no requested class won (declined). - `pages_read_fraction` number: Fraction of expected pages that entered at least one model prompt, from 0 to 1. Equals 1.0 when no pages were unread; otherwise 1 minus unread over expected. - `warnings` string[]: Parse settings this run accepted but did not apply, each naming the setting and why, for example a page selection on a file with no pages. Left out when empty. - `disclosures` union[]: Structured signals about how this result was produced. Empty when all behaviours matched what the caller would assume without them. - union - ClassificationGapFillDisclosure: Pages left unclassified by the model were assigned a fallback label. The classification still succeeded. Gap-filled pages should be treated as lower-confidence assignments rather than absences. One disclosure is emitted per distinct fallback label; ``filled_pages`` in that disclosure are exactly the pages that received ``fallback_label``. - … - ClassificationUnreadPagesDisclosure: Pages never entered any model prompt and are therefore unknown. The classification still succeeded. These pages were dropped by the document-size batch or token cap, so no model produced a label for them. They carry the reserved unknown label regardless of unknown_policy and must not be read as gap-fill (the model never saw them). - … - ExtractionNullOnSuccessDisclosure: Schema-required fields returned null because the document did not contain them. The job succeeded. Null means the document was examined and the field was absent — not that extraction failed or was skipped. - … - ParseVendorProvenanceDisclosure: The file was processed by a vendor other than the router's first choice. The parse result is valid. The vendor name is published so a caller can account for differing output quality or formatting between vendors. - … - ParseFidelityDisclosure: An oversized parse used a bounded fidelity mode without dropping extracted text. - … - ContentTruncatedDisclosure: A user-visible content field was truncated before being included in the result. The result is otherwise complete. ``unit`` states how both size fields should be interpreted. - … - SourceIncompleteDisclosure: The source file ended mid-document, so the result covers only the part that arrived. The job succeeded on the bytes that were present, and a lane that can read a partial file still returns everything it could read. Without this disclosure that output is indistinguishable from a complete document, which is the dangerous reading: a short result looks like a short source. No original size is published because an incomplete file carries no record of how long it should have been. ``received_bytes`` is what a caller can compare against the size it believes it sent. - … - NdiServiceAppPlatformApiResultsCategorizeResult - `result_type` 'categorize' - `assignments` CategoryAssignment[], required - `source_index` integer, required: Index into the request's sources list. - `file_name` string, required - `category` string, nullable: Null when nothing cleared the threshold. - `confidence` number, required - `evidence` Evidence: The citation primitive. Every result that asserts something about a document or the corpus carries it. A synthesised sentence with no evidence behind it is a bug, not a degraded mode. ``path`` is always the uploaded **source** path — that is what every external audience (``/v1`` bodies, the console, the search-agent result) is shown. The two ``exclude=True`` fields below are the host's internal twin of it, for the audience that must not see source paths at all (the agent's tools address ingestion derivatives); they are never serialized, so the ``/v1`` wire shape is exactly what it was before they existed. ``component`` closes the loop from a hit back to the file tools: it is the public component name of the hit — exactly the vocabulary ``file-metadata`` lists and ``qa-file`` / ``read-file`` accept as ``component=`` (the tab name for a spreadsheet, the section/subcategory for a split document). ``None`` means a single-component file or that attribution was unavailable. ``sql_table`` takes the next step for a component that is a table: the name ``run-sql`` queries it under — a spreadsheet tab's table, or the table every row a document prints in its long tables lands in. Search sets it so a hit can go straight to SQL; other producers leave it ``None``. ``locator`` is present only when the producer actually located the snippet. ``None`` is not a degraded mode: an engine that answered from a whole component (the QA agent's quotes, the DuckDB agent's SQL receipts) asserts the file and ``component``, nothing finer. Pinning such a snippet to a region — a page bbox, a sheet cell range — is a separate ``ground`` call on ``path`` with ``snippet`` as the target text (and ``component`` as the ``sheet`` hint when the file is a spreadsheet). - `file_id` string, uuid, required - `path` string, required - `locator` union: Where the snippet sits, when the producer located it. None means the citation is component-level: ground the snippet against path (sheet=component for spreadsheets) to place it. - … - `page` integer, nullable: The 1-based page the producer attributed the snippet to when it produced no locator; None when unknown or when the locator already carries the page. - `relevance_score` number, required - `snippet` string, required - `why` string, required: Which retrieval leg matched, or which graph path led here. - `component` string, nullable: Public component of the hit, in the vocabulary file-metadata lists and qa-file/read-file accept as component= (tab name for spreadsheets, section for split documents); None for a single-component file or when attribution is unavailable. - `sql_table` string, nullable: The run-sql table name holding the hit's component as rows (a spreadsheet tab's table, or a document's printed long tables); None when the component is not a table or the producer does not say. - `line_start` integer, nullable: First line (1-based) of the hit in the text read-file returns for path and component; None when the producer did not place the hit in lines. - `line_end` integer, nullable: Last line (1-based, inclusive) of the hit, counted like line_start; None with it. - `alternatives` ScoredCategory[] - `category` string, required - `confidence` number, required - `units` integer, required - `warnings` string[]: Parse settings this run accepted but did not apply, each naming the setting and why, for example a page selection on a file with no pages. Left out when empty. - NdiServiceAppPlatformApiResultsExtractResult - `result_type` 'extract' - `enrichment_status` 'pending' | 'complete' | 'degraded': Pending means values are available while citations and other enrichment are still running. Complete means enrichment finished; degraded means it finished with a reported enrichment failure. Always read the job status for cancellation or failure. - `data` object: Object shaped by the request schema. Missing values are null, not omitted. - `fields` ExtractedField[], required: One entry per schema field, including not_found. A missing value is never silently dropped. - `path` string, required: JSON Pointer of this schema leaf (for example /invoice_number). Join key between data and fields. - `value` union: Extracted scalar for this path, or null when the field was not found. - string - integer - number - boolean - `status` 'found' | 'not_found' | 'ambiguous', required: Whether this leaf was filled: found has a value, not_found means the document was examined and the field is absent, ambiguous means a value is present but not unique. - `confidence` number, nullable: Evidence-support score for a found top-level scalar when the runtime produced one. Null for nested paths, arrays, not_found, and unverifiable fields. - `citations` Citation[]: Where the value was read. Empty when citations are off or the field was not found. - `location` union, required: Where in the source the value was read. - … - `word_anchor` WordAnchor: Native OOXML paragraph span, independent of converted-PDF pagination. - … - `source_text` string, nullable: Short quote from the source at that location. Null when citations omit source text. - `schema_id` string, nullable: Catalog schema family id when a registry schema was used. - `schema_version` integer, nullable: Catalog version that was frozen at accept time. - `converted_pdf_url` string, nullable: Authenticated PDF preview used to measure citation regions for an office source. - `units` integer, required: Measured work units for this extraction. The job's `credits` is the final billed amount. - `warnings` string[]: Non-fatal notes about the request, e.g. instructions no schema field can satisfy. - `disclosures` union[]: Structured signals about how this result was produced. Empty when all behaviours matched what the caller would assume without them. - union - ClassificationGapFillDisclosure: Pages left unclassified by the model were assigned a fallback label. The classification still succeeded. Gap-filled pages should be treated as lower-confidence assignments rather than absences. One disclosure is emitted per distinct fallback label; ``filled_pages`` in that disclosure are exactly the pages that received ``fallback_label``. - … - ClassificationUnreadPagesDisclosure: Pages never entered any model prompt and are therefore unknown. The classification still succeeded. These pages were dropped by the document-size batch or token cap, so no model produced a label for them. They carry the reserved unknown label regardless of unknown_policy and must not be read as gap-fill (the model never saw them). - … - ExtractionNullOnSuccessDisclosure: Schema-required fields returned null because the document did not contain them. The job succeeded. Null means the document was examined and the field was absent — not that extraction failed or was skipped. - … - ParseVendorProvenanceDisclosure: The file was processed by a vendor other than the router's first choice. The parse result is valid. The vendor name is published so a caller can account for differing output quality or formatting between vendors. - … - ParseFidelityDisclosure: An oversized parse used a bounded fidelity mode without dropping extracted text. - … - ContentTruncatedDisclosure: A user-visible content field was truncated before being included in the result. The result is otherwise complete. ``unit`` states how both size fields should be interpreted. - … - SourceIncompleteDisclosure: The source file ended mid-document, so the result covers only the part that arrived. The job succeeded on the bytes that were present, and a lane that can read a partial file still returns everything it could read. Without this disclosure that output is indistinguishable from a complete document, which is the dangerous reading: a short result looks like a short source. No original size is published because an incomplete file carries no record of how long it should have been. ``received_bytes`` is what a caller can compare against the size it believes it sent. - … - `unrefined_field_paths` string[]: JSON paths of found fields whose citation does not point at the exact line the value was read from: it is a broader document region, or absent. The values are correct. The exact location could not be measured, for example because the quote's words are laid out differently on the page than in the text, or the value is printed identically in several places and nothing said which one. A value is never boxed at its first occurrence instead. Empty when citations are off. - NdiServiceAppPlatformApiResultsGroundResult - `result_type` 'ground' - `targets` GroundTargetResult[], required: One result per request target, in request order. - `id` string, required: Caller-defined id from the request targets list. Join request to result on this, not on quote text. - `status` 'found' | 'not_found' | 'failed', required: Per-target outcome: found has at least one location, not_found means the quote is not in the document (the job still succeeded), failed is a target-level error. - `matches` GroundMatch[]: Locations for this target, sorted best-first and numbered by rank. Empty when not found. - `word_anchor` WordAnchor: Native OOXML paragraph span, independent of converted-PDF pagination. - … - `rank` integer, required: 1-based position in this target's matches after the matcher has sorted hits best-first. 1 is the primary location; later ranks are other occurrences or weaker hits. On an HTML source, a hint ranks the visible occurrence nearest that nearby text first; without a hint, rank 1 is the first visible occurrence. Rank restarts at 1 on every target. The list is capped by options.max_matches. Not a score — use match_method and confidence. - `matched_text` string, required: The string actually found at location. Can differ from the request target text when match_method is normalized or semantic. - `match_method` 'exact' | 'normalized' | 'semantic', required: How this hit was accepted: exact is a character-for-character copy of the target, normalized ignores case and punctuation, semantic is a meaning-similar or visual hit. - `confidence` number, nullable: 0-1 locator confidence when the grounding provider reports one. Independent of match_method: exact and normalized hits can carry a score too. Null only when the provider has no confidence for that match. This is not rank. - `location` union, required: Where the quote was found. Kind follows the source: page_region for PDF or image polygons, text_span for character offsets — into the derived text for most sources, but into the uploaded file itself for HTML and email, so tags and headers are counted — sheet_range for a workbook tab and A1, json_pointer for JSON, jsonl_record for a JSONL line, row_range for table rows, or audio_range for media timestamps. - … - `cropped_image_url` string, nullable: Crop URL when options.include_previews is true and the match has a visual region. - `error` string, nullable: Machine-readable reason when status is failed, for example needle_too_short. Null otherwise. - `units` integer, required: Measured work units for this ground job. The job's `credits` is the final billed amount. - `transcript_url` string, nullable: Storage URL of the MediaTimeline JSON used for grounding. - `converted_pdf_url` string, nullable: PDF the office source was converted to before grounding. Match regions are measured on this PDF. Null when the source was already a PDF or did not need conversion. - `warnings` string[]: Parse settings this run accepted but did not apply, each naming the setting and why, for example a page selection on a file with no pages. Left out when empty. - IngestionResult - `result_type` 'ingestion' - `outcomes` IngestedFileOutcome[], required - `file_id` string, uuid, required - `path` string, required - `status` 'ingested' | 'skipped_unchanged' | 'skipped_empty' | 'failed', required - `lane` string, nullable - `units` integer - `error` Error: The error object, per spec 12 §1.8. - `code` 'storage_connection_not_found' | 'storage_connection_in_use' | 'storage_limit_exceeded' | 'storage_conflict' | 'storage_auth_required' | 'storage_unavailable' | 'scan_required' | 'scan_rejected' | 'scan_unavailable' | 'invalid_request' | 'unsupported_file_type' | 'file_too_large' | 'invalid_schema' | 'invalid_sql' | 'invalid_path_prefix' | 'command_not_permitted' | 'batch_too_large' | 'domain_validation_failed' | 'default_label_required' | 'wait_required_for_zero_retention' | 'ledger_decision_invalid' | 'tenant_required' | 'partner_required' | 'workspace_not_found' | 'file_not_found' | 'job_not_found' | 'upload_not_found' | 'node_not_found' | 'schema_not_found' | 'domain_not_found' | 'session_not_found' | 'access_label_not_found' | 'ledger_understanding_not_found' | 'ledger_table_not_found' | 'tenant_not_found' | 'path_conflict' | 'schema_version_conflict' | 'access_label_name_taken' | 'workspace_name_taken' | 'access_label_in_use' | 'upload_expired' | 'file_not_ingested' | 'workspace_deleting' | 'workspace_not_deletable' | 'ingestion_in_progress' | 'job_not_cancellable' | 'confirmation_required' | 'domain_not_published' | 'domain_in_use' | 'reserved_domain_slug' | 'kg_not_built' | 'kg_build_in_progress' | 'ledger_understanding_in_progress' | 'ledger_understanding_version_outdated' | 'session_busy' | 'tenant_limit_reached' | 'range_not_satisfiable' | 'result_expired' | 'access_denied' | 'tenant_disabled' | 'access_backstop_violation' | 'access_mode_not_implemented' | 'rate_limited' | 'concurrency_limit_reached' | 'quota_exceeded' | 'corrupt_file' | 'zero_byte_file' | 'encrypted_file' | 'csv_dialect_ambiguous' | 'csv_parse_failed' | 'parse_failed' | 'ocr_failed' | 'conversion_failed' | 'sheetless_workbook' | 'unplayable_media' | 'unclassified_pages' | 'job_cancelled' | 'job_timeout' | 'upstream_unavailable' | 'internal_error' | 'unauthorized' | 'not_implemented', required: Every error the ``/v1`` surface can return. Clients must treat this as an **open** enum: a new member is an additive change (spec 12 §9), and a client that crashes on an unknown code makes every future error a breaking change. - `message` string, required: Human- and model-readable; says what to do differently. - `detail` object, nullable: Structured payload, when the code carries one. - `retryable` boolean, required: Whether retrying the identical request could succeed. - `request_id` string, nullable: Per-request correlation id; matches the ``X-Request-Id`` header. Null only when the error was minted outside any HTTP request, e.g. by a worker. - `files_ingested` integer, required - `files_skipped` integer, required - `files_empty` integer: Files skipped because a valid Parquet input contained zero rows. - `files_failed` integer, required - `units_total` integer, required - `kg_build_job_id` string, uuid, nullable: The knowledge-graph build this ingestion chained, when the workspace auto-builds. Poll it to know when the graph covers these files; null means no build was chained (auto-build off, or a pending build already covers them). - `ledger_understanding_job_id` string, uuid, nullable: The ledger-understanding run this ingestion chained. Null when none was: the workspace holds no journal-line table, an artefact for this exact package already exists, one is already queued, or the workspace turned chaining off. - ReconciliationResult: Reconciliation only ever *detects*; ingestion is what acts. - `result_type` 'reconciliation' - `files_scanned` integer, required - `discovered` string[]: In storage, absent from the ledger. - `marked_stale` string[]: observed_hash != ingested_hash. - `orphans_removed` string[]: In the ledger, absent from storage. - `ingestion_job_id` string, uuid, nullable: Set when auto_ingest was requested. - KnowledgeGraphBuildResult: The corpus-level graph build: what one snapshot covered. The graph is a property of the whole corpus, not a per-file derivative, so this reports totals rather than per-file outcomes — with one exception: ``files_failed`` is per-file because a build now finishes without the files it could not process, and "which files is this graph blind to" is otherwise unanswerable from the outside. A file listed there is excluded from ``files_covered`` and stays marked as needing a rebuild. ``snapshot_id`` is the new graph's cache key — the same value ``kg_info`` returns — so a caller can tell the build actually advanced the served graph. - `result_type` 'kg_build' - `snapshot_id` string, required - `status` 'published' | 'empty_no_mentions': published when this build wrote a snapshot. empty_no_mentions when every planned document extracted and none produced a mention, so the job succeeded without publishing a snapshot. - `files_covered` integer, required: Source files whose ledger version matched the build-time corpus at finalize; files replaced during the build are excluded and will show as needing a rebuild. - `node_count` integer - `edge_count` integer - `rebuilt` boolean: True when a force build cleared the prior store first. - `files_failed` KnowledgeGraphFileFailure[]: Files quarantined after exhausting their retries. Not in the graph, and not marked covered. - `path` string, required - `phase` 'classifying' | 'extracting', required: Where it failed: 'classifying' (never registered) or 'extracting'. - `error` string, required: The verbatim final cause, as the failing step reported it. - LedgerUnderstandingResult: One package's settled reading, as the understanding job publishes it. The result IS the report: the route's ``GET`` and ``GET /v1/jobs/{id}`` answer with the same object, so a caller that polled the job never has to call a second endpoint to learn what the run concluded. - `result_type` 'ledger_understanding' - `follow_up_job_id` string, uuid, nullable: Selected-package measurement job chained by discovery. - `report` LedgerUnderstandingReport, required - `artifact_version` integer, nullable: Compatibility version that produced this report; absent on legacy job results. - `current_version` integer, nullable: Compatibility version of the server that returned this response. - `rerun_required` boolean: Whether a new understanding run is needed to obtain a current report. - `auto_decisions` AutoDecisionWire[]: Automatic choices, suggestions and refusals from this reading. - `slot` string, required: Binding question addressed by the automatic checkpoint. - `outcome` 'accepted_sole' | 'accepted_model' | 'suggested' | 'refused' | 'unanswered' | 'nominated', required: Checkpoint outcome after deterministic validation; a nominated journal identity was sent to complete-population measurement, which alone can accept it. - `choice` string, nullable: Offered alternative selected or suggested. - `confidence` 'high' | 'medium' | 'low', nullable: Model confidence before validation. - `rationale` string, nullable: Model explanation of its choice. - `detail` string: Validation reason or deterministic evidence. - `engine` 'measured' | 'llm': Configured discovery engine for this reading. - `proposals` LedgerPackageProposals - `auto_confirmation` AutoConfirmation - … - `tie_break` PackageTieBreak - … - `candidates` PackageCandidate[]: Validated nominations in model rank order. - … - `model_slug` string, required: Model used to nominate packages. - `catalog_revision` string, required: Accessible catalog revision used for nomination. - `triaged_out` string[]: Bounded sample of omitted source handles and short reasons. - `warnings` string[]: Discovery limitations, including heuristic fallback after empty triage. - `heuristic_fallback` boolean: Whether composition ran over rank-ordered catalog sources because triage nominated none. - `triaged_out_count` integer: Total sources omitted from composition, including those beyond the displayed sample. - `rejected` RejectedCandidate[]: Nominations refused by catalog validation. - … - `duration_ms` integer: Elapsed discovery time in milliseconds. - `input_tokens` integer: Total input tokens across model calls and retries. - `output_tokens` integer: Total output tokens across model calls and retries. - `reading_id` string, nullable: Immutable reading identity to echo when answering source-selection HITL; absent on legacy reports. - `scope` LedgerPackageScope: A package's source files: every file under the prefix plus every explicit path. - `path_prefix` string, nullable: Folder containing the package, relative to the workspace root. - `paths` string[]: Exact source paths in the package, added to every path under the prefix. - `selection_id` string, uuid, nullable: Protected, immutable source-role selection reference. - `assessment` LedgerAssessmentWire: Evidence-based assessment independent of job success and structural blocking. - `status` 'ready' | 'limited' | 'needs_scope' | 'needs_source_selection' | 'needs_decision' | 'execution_failed' | 'unknown': Summary; inspect procedure readiness and execution coverage before relying on results. - `reasons` string[]: Why the summary is not fully ready. - `planned_checks` integer: Statements planned, excluding missing-prerequisite skips. - `completed_checks` integer: Statements completed, including zero-finding results. - `failed_checks` integer: Planned statements that failed execution. - `skipped_checks` integer: Checks not planned because prerequisites were absent. - `not_run_checks` integer: Planned statements withheld after an earlier resource failure. - `execution_coverage` number, nullable: Completed over planned statements; null when unknown or none planned. - `procedures` object: Procedure-specific readiness, not a JET gate. - `populations` PopulationCandidateWire[]: Bounded same-scope candidate evidence. - … - `population_count` integer: Total candidate count before bounding the evidence list. - `source_review_available` boolean: Whether this completed current reading can open the source-review correction flow. - `structure_review_available` boolean: Whether complete measured schema supports a structural proposal, not key acceptance. - `header_status` 'not_required' | 'unmeasured' | 'complete' | 'partial' | 'unsafe' | 'failed': Declared header tuple's exact coverage and cardinality verdict. - `header_unmatched_lines` integer, nullable: Unmatched lines retained by optional LEFT JOIN enrichment. - `header_duplicate_keys` integer, nullable: Excess header rows on the complete declared tuple. - `package_fingerprint` string, required: Identifies the exact selected files this reading measured. It moves whenever one of those files is re-ingested, made visible, or replaced. - `produced_at` string, date-time, required: When the stage finished measuring this package. - `stale` boolean, required: Whether the workspace has moved since this reading was measured. A stale report is still returned, because an old measurement a reader can date beats no answer at all. - `stale_reason` 'package' | 'version' | 'decisions', nullable: Why it is stale, when it is: 'package' means files were ingested, replaced or made visible since; 'decisions' means somebody has answered a review this reading did not fold. They are different actions — the first is re-measured by a plain run, the second by applying the decisions. 'version' means this build's measurement rules changed. Precedence is package, version, then decisions; the version fields and pending decision count retain the other reasons when several apply. - `pending_decisions` integer: Decisions stored for this workspace that this reading did not fold. Zero on a reading that is current with every answer given. - `applied_decisions` AppliedDecisionWire[]: What this reading did with each decision it folded, including the ones it could not apply. - `kind` 'role_slot' | 'parse_signature' | 'period_mapping' | 'encoding_mapping', required: Which kind of reviewable thing it was about. - `key` string, required: The binding slot, or the parse signature — the same key the decision was written under. - `outcome` 'applied' | 'orphaned' | 'conflict', required: 'applied': folded in. 'orphaned': this reading has nothing open under that key, usually because the data now settles it. 'conflict': the question stands but the answer is not one of the alternatives it offers, so re-answering it is what clears this. - `detail` string: Why, when the outcome is not 'applied'. - `blocking` boolean, required: Mirrors the integrity report's structural verdict, so a caller can branch on one field. - `tables` TableCardWire[], required: Every queryable table in the package, with its grain figures. - `path` string, required: The source file this table was ingested from. - `component` string, nullable: The worksheet or tab inside that file, where it has one. - `table_name` string, required: The name SQL over this workspace registers the table under. - `role` string, required: What this table is in the package: journal_lines, journal_headers, trial_balance, chart_of_accounts, calendar, user_master, source_listing, or other. - `rows` integer, required: Rows in the table, as the ingest census counted them. - `line_shaped` boolean, required: Whether this table is a journal-line file: a journal key and either a debit/credit pair or a live-measured signed amount. - `partition_family` string, nullable: The family this table shares with its siblings when one ledger is split per period. - `journal_key` string[], nullable: The columns the accepted journal key is spelled over, or null when none qualified. - `key_balanced_share` number, nullable: Share of that key's groups netting to zero on the tested amount basis. - `key_median_lines` number, nullable: Median lines per journal under that key. - `columns` ColumnCardWire[], required: Every column of the table, in the table's own column order. - … - `conventions` ConventionsWire, required: What this package's numbers mean, in the terms every test is defined in. - `ledger_tables` string[], required: The tables that hold the journal lines under test. - `header_table` string, nullable: The journal-header table, where the package has one. - `journal_key` string[], nullable: The columns one journal entry is identified by. - `journal_key_aliases` string[]: Other scalar columns proven to identify exactly the same groups of ledger rows. - `account_column` string, nullable: The visible account column selected for journal lines. - `account_columns` string[]: The ordered account identity selected for journal lines. - `account_scope_columns` string[]: Hidden source dimensions used to keep segmented accounts distinct. - `account_identity_status` 'legacy' | 'scalar' | 'scoped' | 'blocked' | 'unmeasured': Whether complete-population evidence proved the account identity safe. - `account_identity_reason` string, nullable: Aggregate account-identity proof or refusal reason. - `bases` BasisWire[], required: Every amount basis the package spells, with its balance measurement. - … - `date_roles` object, required: Each date role the stage settled mapped to the column that fills it, using the role vocabulary. - `auxiliary_columns` object: Non-exclusive SAP meanings and their qualified physical columns. - `role_sources` object: Physical owner and evidence per settled role. - `unavailable_tests` string[], required: Tests this package cannot run because a role they need is absent. Stated rather than left silent, since silence about an untested condition reads as a clean result. - `header_columns` string[], required: Attributes the journal key determines — one value per journal. - `line_columns` string[], required: Attributes that vary within a single journal. - `entity_column` string, nullable: The column carrying the reporting entity, where one is settled. - `entity_values` string[], required: The entity values present, where the census knows the domain entire. - `period_column` string, nullable: The column carrying the accounting period axis. - `period_values` string[], required: The period values present, where the census knows the domain entire. - `layer_column` string, nullable: The book or overlay axis, where exactly one column carries one. Its split stays open. - `one_sided_entries` 'none' | 'present' | 'unknown', required: Whether the package holds journals that post to one side only, or whether nothing measured it. - `integrity` IntegrityReportWire, required: Whether this population is fit to test, and what could not be asked. - `findings` IntegrityFindingWire[], required: Everything the battery established, in plan order. - … - `skipped` SkippedCheckWire[], required: Checks that did not run. Reported rather than dropped, because an untested condition and a clean one are different answers. - … - `blocking` boolean, required: Whether the package is missing something structural — a balanceable amount, a date, or an account — which is the only condition that stops the stage going further. - `executions` CheckExecutionWire[], nullable: Per-statement outcomes; null on legacy readings. - … - `join_graph` JoinEdgeWire[], required: The expected joins between the package's tables, with their ratios. - `left_table` string, required: The table the edge is measured from. - `left_column` string, required: The column on that table the edge joins on. - `right_table` string, required: The table the edge is measured against. - `right_column` string, required: The column on that table the edge joins on. - `left_columns` string[]: Ordered composite source key; empty means the scalar column. - `right_columns` string[]: Ordered composite reference key; empty means the scalar column. - `left_tables` string[]: Selected population members measured together; empty means the scalar table. - `left_null_rows` integer, nullable: Source rows with a missing key component. - `right_null_rows` integer, nullable: Reference rows with a missing key component. - `right_duplicate_keys` integer, nullable: Reference keys appearing more than once, making row enrichment unsafe. - `left_in_right` number, nullable: Share of the left column's distinct values that appear in the right. - `right_in_left` number, nullable: Share of the right column's distinct values that appear in the left. - `unmatched_left` integer, nullable: Distinct left values with no match on the right. - `unmatched_right` integer, nullable: Distinct right values with no match on the left. - `open_questions` OpenQuestionWire[], required: What the data could not settle and a reader must decide. - `id` string, required: A stable id within this report, assigned after a deterministic sort. - `slot` string, required: The binding slot or convention this question is about. - `question` string, required: The question, phrased so it can be answered from the package itself. - `candidates` string[], required: The alternatives the data leaves open, where it narrows them at all. - `evidence` string[], required: What the census measured about the choice, one line per measurement. - `exclusive_group` string, nullable: Questions sharing this group take distinct columns; null when the question stands alone. - `parsing` ParseSummaryWire: What general-ledger parsing made of the package (§9). Counts, never rows: the mapping itself is a derived table the testing engine joins, and a report that carried it would be a download. The five outcome counts add up to ``journals_total`` by construction — every journal is represented exactly once, and a hub, an unbalanced entry or a capped one is a named outcome rather than a missing row. The parquet URLs are withheld for the reason the receipts' SQL is: they name internal storage keys, and a caller has no route that reads them. - `resource_failure` 'spill_capacity' | 'memory', nullable: Exhausted engine resource that prevented parsing. - `journals_total` integer, required: Journals found in the ledger, on the accepted journal key. - `candidates` integer, required: Journals holding enough account/debit-credit groups to be worth splitting. - `attempted_candidates` integer: Candidate journals actually evaluated by the parser. - `candidate_coverage` number, nullable: Attempted candidates divided by all candidates, or null when none exist. - `population_capped_share` number, nullable: Population-capped candidates divided by all candidates, or null when none exist. - `cap_reason_counts` object: Distinct journals per exact parse stop reason, including the population cap. - `cap_profiles` object: Group and posting count distributions by exact stop reason. - `candidates_capped` boolean, required: Whether the population cap cut the candidate set. - `population_capped` integer, required: Candidates the cap excluded; published whole rather than dropped. - `parsed` integer, required: Journals split into more than one balanced sub-journal. - `identity` integer, required: Journals that were never bundles, so each is its own sub-journal. - `hub` integer, required: Journals where one control account offsets every other — correctly left whole. - `unbalanced` integer, required: Journals whose own lines do not net to zero. - `capped` integer, required: Journals left whole because a bound stopped the parse rather than a reading. - `solver_cap_hits` integer, required: Of those, the ones the solver itself refused. - `sub_journals_total` integer, required: Sub-journals published across the whole ledger. - `per_bucket` object, required: Sub-journals per confidence bucket, keyed '1'–'4': 1 proven, 2 reserved, 3 ambiguous and available on demand, 4 refused as a split. - `basis` string, nullable, required: The amount basis the parse netted on, or null when it was skipped. - `decimals` integer, nullable, required: The minor-unit scale the parse netted at. - `parse_run_id` string, nullable, required: Identity of this parse: the package, the version, and its parameters. - `duration_ms` integer, required: Milliseconds the parsing pass spent on this package. - `skipped_reason` string, nullable, required: Why no mapping was produced, when none was. A skipped parse is a recorded answer: the rest of the report stands and the tables are simply absent. - `confirmation_required` MappingConfirmationRequired - … - `tables` DerivedTableWire[], required: The published tables, empty when the pass was skipped. - … - `preparations` PreparationSummaryWire[]: Reusable relationship preparations requested for this package; empty when none were configured. - `name` string, required: Stable configured relationship name. - `status` 'ready' | 'unavailable' | 'failed', required: Whether a complete reusable generation was published. - `reason` string, nullable: Bounded reason when the relationship is not ready. - `reused` boolean: Whether an existing complete generation was reused. - `bucket_count` integer, nullable: Published bucket count when preparation is ready. - `left_rows` integer, nullable: Rows published for the left side when ready. - `right_rows` integer, nullable: Rows published for the right side when ready. - `size_bytes` integer, nullable: Combined byte size of both published sides when ready. - `duration_ms` integer: Milliseconds spent loading or preparing this relationship. - `settled_structure` StructureProposal - `journal_key` string[], required: Ordered identity to measure, not an accepted key. - `amount` union, required: Amount basis to measure over the whole primary. - … - `account` union, required: Line-owned account column or ordered composite account identity. - … - `effective_date` string, nullable: Optional line-owned effective date column. - `period` string, nullable: Optional period column; does not interpret its values. - `line_ordinal` string, nullable: Optional ordinal whose uniqueness is checked within each journal. - LedgerUnderstandingResetResult: What one ledger-understanding reset removed. Counted rather than merely reported done, for ``DeleteFileResult``'s reason: a caller who asked for a reset can see it happened. ``verified`` comes from an independent re-read of the prefix, and a false one is an alertable fact on a job that still succeeded — failing the job would hide these counts. - `result_type` 'ledger_understanding_reset' - `workspace_id` string, uuid, required: The workspace whose ledger reading was removed. - `objects_deleted` integer: Stored objects removed across the stage's own prefix and the je-testing prep prefix. - `decisions_deleted` integer: Stored review answers cleared across every package; the rows stay, emptied. - `jobs_cancelled` string[]: Runs stopped because they were reading what this reset removed. - `verified` boolean: False is a failed reset and must alert. - LedgerParseExhibitsResult: Which parse run's GL parse examples are published, read from the manifest that commits them. The examples themselves stay behind the explorer routes; this names what a succeeded job made readable, so success always has something to point at. - `result_type` 'ledger_parse_exhibits' - `parse_run_id` string, required: The parse run whose journals the published examples rank and locate. - `journals_total` integer, required: Journals the published examples cover, equal to the parse's own count. - UploadFileResult: Also the result of ``JobKind.UPLOAD_SESSION_COMPLETE``. A chunked upload's completion produces exactly this shape — the file it landed, and whether it deduplicated — so it deliberately reuses this result rather than minting a near-identical discriminated variant whose ``result_type`` would just be a second name for the same two fields. - `result_type` 'file_upload' - `file` File, required: A source file. The derived tree is platform-owned and has no CRUD surface. - `file_id` string, uuid, required - `workspace_id` string, uuid, required - `path` string, required: Full path relative to the workspace root. Send this exact string wherever a tool takes `path`: tools match it exactly. - `file_name` string, required: The last segment of `path`, for display only. A tool given it as `path` answers file_not_found. - `file_type` string, required - `size_bytes` integer, required - `observed_hash` string, required - `ingested_hash` string, nullable: Content hash at the last successful ingestion. Null with ingested_at means never ingested. - `ingestion_status` 'discovered' | 'queued' | 'ingesting' | 'ingested' | 'stale' | 'expired' | 'failed' | 'not_required', required: The only thing that says whether a file is searchable. ``expired`` cannot be derived from the hash pair: retention clears ``ingested_hash``, so an aged-out file and a never-ingested file look identical. They call for different customer actions, so the status carries the distinction the hashes cannot. - `ingested_at` string, date-time, nullable - `version` integer, required: Starts at 1; increments on every content replacement. - `category` string, nullable: Null until categorised. - `access_label` string, nullable: Exactly one label, or null when the workspace declares none. - `access_label_source` 'inherited' | 'classified' | 'mirrored': Which mechanism produced a document's label. The ``default_label`` fallback records as ``inherited``, so an audit can tell a real classification from a fallback. - `expires_at` string, date-time, nullable: When derived material for this file ages out. - `graph_inclusion` 'auto' | 'include' | 'exclude': This file's knowledge-graph inclusion policy, not its effective membership. 'auto' defers to the workspace's KG exclusion rules; 'include'/'exclude' override them for this one file. A file excluded by a workspace rule still reads 'auto' here, so this does not on its own tell an excluded file from one whose graph is not built yet — read representations.knowledge_graph for whether a build has covered it. - `labels` object: Caller-supplied metadata. - `created_at` string, date-time, required - `updated_at` string, date-time, required - `deduplicated` boolean, required: Identical bytes were already present. - ReplaceFileResult - `result_type` 'file_replace' - `file` File, required: A source file. The derived tree is platform-owned and has no CRUD surface. - `file_id` string, uuid, required - `workspace_id` string, uuid, required - `path` string, required: Full path relative to the workspace root. Send this exact string wherever a tool takes `path`: tools match it exactly. - `file_name` string, required: The last segment of `path`, for display only. A tool given it as `path` answers file_not_found. - `file_type` string, required - `size_bytes` integer, required - `observed_hash` string, required - `ingested_hash` string, nullable: Content hash at the last successful ingestion. Null with ingested_at means never ingested. - `ingestion_status` 'discovered' | 'queued' | 'ingesting' | 'ingested' | 'stale' | 'expired' | 'failed' | 'not_required', required: The only thing that says whether a file is searchable. ``expired`` cannot be derived from the hash pair: retention clears ``ingested_hash``, so an aged-out file and a never-ingested file look identical. They call for different customer actions, so the status carries the distinction the hashes cannot. - `ingested_at` string, date-time, nullable - `version` integer, required: Starts at 1; increments on every content replacement. - `category` string, nullable: Null until categorised. - `access_label` string, nullable: Exactly one label, or null when the workspace declares none. - `access_label_source` 'inherited' | 'classified' | 'mirrored': Which mechanism produced a document's label. The ``default_label`` fallback records as ``inherited``, so an audit can tell a real classification from a fallback. - `expires_at` string, date-time, nullable: When derived material for this file ages out. - `graph_inclusion` 'auto' | 'include' | 'exclude': This file's knowledge-graph inclusion policy, not its effective membership. 'auto' defers to the workspace's KG exclusion rules; 'include'/'exclude' override them for this one file. A file excluded by a workspace rule still reads 'auto' here, so this does not on its own tell an excluded file from one whose graph is not built yet — read representations.knowledge_graph for whether a build has covered it. - `labels` object: Caller-supplied metadata. - `created_at` string, date-time, required - `updated_at` string, date-time, required - `previous_version` integer, required - DeleteFileResult: Counts exist so the cascade is auditable rather than assumed. - `result_type` 'file_delete' - `file_id` string, uuid, required - `outputs_deleted` integer - `index_documents_deleted` integer - `kg_nodes_deleted` integer - `kg_edges_deleted` integer - `jobs_cancelled` string[] - `verified` boolean, required: False is a failed cascade and must alert. - DeleteFilesResult: A batch deletion's per-file outcomes plus the cascade's own counts. The counts are summed over the files that were actually deleted, and exist for the same reason ``DeleteFileResult``'s do: a caller that asked for deletion can verify it happened rather than assume it. ``verified`` is the conjunction over the batch, and ``unverified_file_ids`` names the files behind a false one — an aggregate flag alone would say a cascade failed without saying for what. - `result_type` 'files_delete' - `requested` integer, required: How many file ids the batch named, after duplicates were dropped. - `deleted` integer, required: How many of them were soft-deleted and cascaded. - `outcomes` FileDeletionOutcome[], required: One entry per requested file, in the order requested. - `file_id` string, uuid, required: The requested file, echoed whether or not it was deleted. - `path` string, nullable: The deleted file's workspace-relative path; null when the id resolved to no visible file. - `status` 'deleted' | 'not_found' | 'access_denied', required: Whether this file was soft-deleted, did not exist in the workspace, or was withheld by the access gate. - `outputs_deleted` integer: Live derived outputs retired across the batch. - `index_documents_deleted` integer: Search-index documents removed across the batch. - `catalog_rows_deleted` integer: Catalog records and source handles removed across the batch. - `objects_deleted` integer: Stored objects removed from the deleted files' sibling folders. - `jobs_cancelled` string[]: In-flight jobs that named a deleted file and were cancelled by the cascade. - `unverified_file_ids` string[]: The deleted files whose re-check still found content in some representation. - `verified` boolean, required: False is a failed cascade and must alert. - WorkspaceDeleteResult: Hard tenant deletion: storage prefix, indexes, and graph. - `result_type` 'workspace_delete' - `workspace_id` string, uuid, required - `files_deleted` integer - `index_documents_deleted` integer - `kg_nodes_deleted` integer - `prefix_deleted` boolean - `verified` boolean - TenantPurgeResult: The tenant's content is gone; no row is deleted: its billing record and metadata rows stay, de-identified. ``verified`` is true only when every store reports nothing remaining. An unfinished cancelled job counts against ``jobs`` and a workspace teardown that could not verify its own storage, index and graph counts against ``workspaces``. A purge that ends unverified is a ``succeeded`` job on purpose, like a workspace delete: the report says what is left, and a second DELETE re-runs it. - `result_type` 'tenant_purge' - `tenant_id` string, uuid, required: The tenant whose data was purged, as NDI identifies it. - `external_ref` string, required: The partner's own reference the tenant had. It stops resolving once the purge succeeds. - `verified` boolean, required: True when no content of the tenant remains anywhere and every kept metadata row is de-identified. - `stores` TenantPurgeStoreReport[], required: One line per store, with what the verification pass still found. - `store` 'jobs' | 'workspaces' | 'files' | 'upload_sessions' | 'profile_cache' | 'answer_cache' | 'catalog' | 'ledger_decisions' | 'parse_exports' | 'webhooks' | 'api_keys' | 'members' | 'users' | 'cli_sessions' | 'limit_overrides' | 'schemas_and_labels' | 'perception_cache' | 'storage' | 'redis', required: One place tenant data lives, and so one line of a purge's verification report. A purge never deletes a Postgres row: each store's rows are emptied or de-identified and marked deleted, and only stored objects and Redis keys are removed. - `remaining` integer, required: Rows that still hold the tenant's content or identifying data or still grant access, objects, and open executions still found there. Kept rows that are already emptied do not count. Zero when clean. - `billing_record_kept` boolean, required: True when the content-free billing record (job ids, kinds, timestamps, units, credits) was kept. - IntelligentSearchResult - `result_type` 'intelligent_search' - `claims` DeepSearchVerifiedClaim[]: Calculated answer values bound to recorded executions. - `claim_id` string, required: Unique id of this calculation within the result. - `answer_excerpt` string, nullable: Exact displayed answer value selected for its calculation citation. - `answer_occurrence` integer: Zero-based occurrence of answer_excerpt in the answer. - `evidence_indices` integer[]: Source evidence indices supporting the calculation inputs. - `claim` string, required: The method or formula behind the calculated value, as the agent wrote it. - `reference` DeepSearchClaimReference, required: A claim's address within a published SQL or command execution receipt. - `kind` 'result_cell' | 'result_count' | 'result_absence' | 'command_result', required: How the result supports the claim. - `result_id` string, required: The matching result_id in sql_receipts or command_receipts. - `row` integer, nullable: 0-based result row for a cell claim; null otherwise. - `column` string, nullable: Result column for a cell claim; null otherwise. - `cited_value` string, required: The exact value checked against the retained result. - `command_receipts` CommandReceipt[]: Successful shell calculations cited by this answer. - `result_id` string, required: Job-scoped identity of a recorded shell execution. - `command` string, required: The shell command as executed. - `stdout` string, required: The complete standard output of the successful command. - `outputs` object, required: Named scalar outputs parsed from stdout; a scalar output is named value. - `sql_receipts` SqlReceipt[]: SQL executions supporting calculated answer claims. - `result_id` string, required: Stable per-run identity of this statement, in execution order (e.g. 'sql_3'). - `sql` string, required: The statement as executed, verbatim. - `handle` string, nullable: Content-addressed key of this statement's stored result, derived from the statement text. Server-side identity: it is what lets the run's own publication find the stored result and its capture-time provenance, and it is NOT an address an agent may query or chain from — `result_id` is the identity the caller and the row pager use. Null on a run that stored no result for the statement. A `cat_` handle names an exploratory document-catalog query: it stores no result beyond the rows carried here. - `table_bindings` SqlTableBinding[]: The tables this statement registered, each with the view name it was referenced by. - `path` string, required: The uploaded table file this view read, e.g. 'ledger/journal.xlsx'. - `component` string, nullable: The source worksheet, including when selected alone. Null for a direct upload or a historical unnamed tab. - `table_name` string, required: The view name the SQL referenced this table by, for THIS run. - `source_sha256` string, nullable: SHA-256 identity of the ingested source generation behind this table binding. - `replay` SqlReplayReceipt: Immutable inputs and engine identity for independent result recomputation. - `schema_version` 1 - `kind` 'aggregate' | 'rowset', required: The verification lane appropriate for this statement. - `engine` 'duckdb', required: The query engine that executed the statement. - `engine_version` string, required: The query-engine version that executed the statement. - `engine_threads` integer, required: DuckDB thread count used for this execution. - `normalized_sql` string, required: The normalized single SELECT statement to execute during independent replay. - `sql_sha256` string, required: SHA-256 identity of the normalized statement. - `logical_plan_sha256` string, required: SHA-256 identity of the parser tree after source-position fields are removed. - `catalog_sha256` string, required: SHA-256 identity of the ordered source bindings used by this statement. - `result_artifact_sha256` string, required: SHA-256 identity of the complete retained result Parquet produced by the service. - `result_data_sha256` string, required: SHA-256 identity of the complete typed result rows. - `result_digest_version` string, required: Versioned Arrow serialization scheme used for the typed-result identity. - `result_dependencies` string[]: Earlier retained result handles read by this statement, in deterministic order. - `columns` string[]: Result column names, in result order. - `rows` object[]: Result rows, values rendered as text so a decimal, a date and a NULL all survive the wire. - `row_count` integer: Rows carried below — not the statement's unbounded result size. - `result_row_count` integer: Rows in the statement's complete stored result. Equal to `row_count` when nothing was cut; the number a total or an exception count must be read from when `truncated` is set. - `truncated` boolean: Whether rows past the stored cap were cut from this receipt. - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Whether this statement's stored result already carried proof of which source rows it read when the receipt was recorded. 'exact' means it did; 'unavailable' means the proof could not be read; 'zero_result' means there were no rows to ground. Null when nothing had been captured yet — the ordinary case for a lane that captures at publication time, so this is a record of what execution happened to know and NOT a prediction of whether the receipt can be grounded. What was actually proven is published as `grounding_status` on the matching evidence query, beside the `regions` it earned. - `views_used` string[]: Session views registered when this statement ran, in definition order — the registry snapshot it executed under. A statement naming a view is replayable only against these, which is what makes named views admissible where chaining a previous call's result handle is not. - `saved_as` string, nullable: The session view this statement was registered as, when it was. Every name in another receipt's ``views_used`` appears here on exactly one receipt, so the run's receipts define every view they cite. - `view_sql` string, nullable: The definition registered under `saved_as`, when it is not this statement itself. Null on an ordinary `save_as`, where `sql` IS the definition. Set by `build_journal_view`, which registers the per-journal frame and runs a bounded probe over it rather than materializing the whole frame — so the definition every later `views_used` refers to is still published by exactly one receipt. - `warnings` string[]: Pre-execution lint notes attached to this statement — non-blocking, and published as part of its working. - `executor` string, nullable: The named executor that generated this statement (`reconcile_movement`, `test_timing`, `find_duplicates`, `field_completeness`, `journal_balance`), when one did, `custom_sql` for a statement the fixed-pipeline engine authored under its escape, or `ledger_understanding` for the ledger-understanding census's own statement, which ran before this run and is cited rather than re-run. Null when no named generator produced it — a population count, an absence probe, or SQL the agent wrote itself. Both engines use the same words here. - `parameters` object: The executor's resolved call, flattened to text — the clock and its true grain, the window's day offsets, the signature, the tolerance, the population. Empty on a statement no executor generated. This is what makes a figure trace to a named, parameterized computation rather than to SQL alone. - `evidences` SearchEvidence[]: The evidence the agent found for the query, in order of importance. - `source_path` string, required: The uploaded file the quote belongs to, e.g. 'reports/policy.pdf'. This is the file to ground the quote against. - `source_file_id` string, uuid, nullable: The id of the file at source_path, resolved server-side. Always set on newly finalized results; null only on results stored before unresolvable citations were dropped. - `page` integer, nullable: 1-based page number, when the agent saw one. - `component` string, nullable: Public component of the file the quote came from — the tab name for a spreadsheet, the section for a split document; the same vocabulary file-metadata lists. Pass it as the ground target's sheet when grounding a spreadsheet quote. None for a single-component file or when attribution was unavailable. - `quote` string, required: The key passage, as retrieved from the file. - `passages` string[]: Contiguous pieces of the source file that quote was stitched from, in the file's own text. Ground each piece as its own target when this list is present, with max_matches 2. A piece that returns two matches repeats in the file, so which copy the quote used is unknown. A ' | ' marks a table cell boundary added by the check. Replace it with a space before grounding. Filled only for PDF, Word and PowerPoint sources that Ground reads from the PDF text layer. Absent when quote is already one contiguous passage, could not be checked, or could not be verified. - `relevance` string: Deprecated: empty on new results, where `reasoning` says how the evidences support the answer. - `queries` TableQueryGrounding[]: The SQL the run executed over this evidence's table, with a bounded preview of each result — server-recorded from the run's tables engine, never model-authored. Attached whenever the run queried the cited table (or the row extraction of the same spreadsheet tab), so a verbatim quote from a queried sheet carries the computation trail alongside it; empty when the run never queried the cited file's tables. - `sql` string, required - `supports_answer` boolean: False for exploratory SQL the tables engine ran but did not mark as part of the answer's calculation trail. - `result_id` string, nullable: Stable identity of the stored query result behind this receipt. Lets the grounding-rows endpoint replay this exact query for matched-row pages beyond the regions' inline runs. - `source_paths` string[]: The uploaded table files this query read — directly, or through a prior result it built on — e.g. 'planning/FS GF Custom.xlsx'. - `row_count` integer: Rows in the query's full result, not in the preview below. - `columns` TableQueryColumn[] - … - `rows` object[]: Leading result rows, values rendered as text — a bounded preview, never the full result. - … - `preview_truncated` boolean: Whether the preview cut rows or columns. - `verified` boolean: True when at least one claim behind this query passed mechanical verification against the source data. Independent of 'regions': a source without an addressable grid verifies but cannot be pointed at, so an empty 'regions' never means unverified. - `regions` union[]: Original-file coordinates for the verified claims whose source file has an addressable grid. - … - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Capture-time provenance status behind this query's regions. 'exact': the exact-provenance sidecar proved every row the query read, so its 'provenance'-basis regions are trustworthy (source regions may be broader than the minimal contributing set when grounding_reason carries a 'regions_broad:…' qualifier). 'unavailable': no exact proof could be captured (a legacy result, or a statement shape the capturer cannot instrument) — no 'provenance'-basis regions are attached, never a guessed whole-table span. 'zero_result': the query matched no rows, so there is nothing to ground. None on legacy payloads and on a query with no unclaimed table left to ground. - `grounding_reason` string, nullable: Qualification on grounding_status, when present. Set for 'unavailable' (explains why proof was not possible) and for 'exact' when capture succeeded but the source regions are broader than the minimal contributing set (e.g. 'regions_broad:narrowing_specs_unavailable'). None when grounding is fully exact or absent. - `derivation` DerivationTrace: The answer's computation DAG when evidence is derived rather than extracted. - `steps` DerivationStep[] - … - `reasoning` string, nullable: The agent's account of how the pieces of evidence chain together to address the query, including any assumption it made in reading the query. - `answer` string, nullable: A direct answer to the query, grounded in the evidences. Always present on a newly finalized run that answered; null when the run rejected the query with a `clarification`, and on results stored before answers became unconditional (the evidence-only mode). - `structured_answer` unknown - `clarification` string, nullable: Non-null exactly when the run rejected the query as genuinely ambiguous instead of answering — only possible when the request set `allow_clarification`: one direct question back to the caller, with `answer` and `reasoning` null and `evidences` empty. Answer it by re-asking in the same thread via the result's `session_id`. - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - `coverage` Coverage: What the access gate withheld, in counts and label names only. Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request. - `restricted_candidates` integer - `labels_required` string[]: Which labels would have been needed to see the withheld candidates. - `request_access_hint` string, nullable - `candidates_seen` integer - `steps_used` integer - `exhausted` boolean: Budget hit before the loop was satisfied. A successful response, not a failure. When the agent authored no answer or reasoning, reasoning carries an actionable briefing and answer stays null so presentation does not treat the briefing as an answer. - `tool_calls` ToolCallTrace[] - `tool` string, required - `arguments_digest` string, required - `hits` integer, required - `duration_ms` integer, required - `session_id` string, uuid, nullable: The conversation this run belongs to. Send it back as the request's `session_id` to ask a follow-up in the same thread. Null only on results finalized before sessions existed. - `cache` AnswerCacheInfo: How a search answer relates to the workspace's semantic answer cache. Present only on a run that served a previously derived answer instead of deriving a new one. Everything else on the result — the evidences, the reasoning, the tool-call trace, the receipts — describes that ORIGINAL derivation, which is what this block exists to say out loud: the answer was computed once, for a question near enough to this one, under an identical scope and an identical access gate, and re-checked against the workspace before it was handed back. A result with no ``cache`` block was derived by the run that returned it. - `served_from_cache` boolean, required: True when this result was re-served from a previously derived answer rather than computed by this run. Always true where this block appears at all. - `source_job_id` string, uuid, nullable: The job whose run originally derived this answer. Null when that job's row has since been reaped — the answer outlives the record of the run that produced it. - `cached_at` string, date-time, required: When the answer was originally derived. Read it as the age of the evidence: the workspace may have changed since, which is what the re-check below is for. - `verified_at` string, date-time, required: When this run re-checked the cached answer's citations against the workspace and accepted them. Always this run's own time — a cached answer is never served unchecked. - `usage` SearchLlmUsage: What answering one search query cost in LLM work. Present only when the run was asked to account for itself *and* spend reached its ledger; ``null`` otherwise, so a caller can tell "nothing was measured" from "nothing was spent". An empty ledger publishes ``null`` rather than a zeroed object for that reason: zeros would claim a measured run cost nothing, when what an empty ledger most likely records is accounting that never landed. The totals cover recorded model calls at any depth: the agent's own turns, and the calls the retrieval tools made on its behalf — a document read by the recursive-LLM engine, a scan cracked by the vision engine, a tables question answered by the SQL agent. That is the number a per-query cost figure needs, and it is invariably several times the agent's own turn count. ``by_model`` is the same spend split by the model that served it, because a run legitimately spends on several at different prices — a total alone cannot be turned into money. The totals are the sum of ``by_model`` and are published anyway so the common case needs no arithmetic. Observed retries are included. These public token totals are not a complete cost certificate: provider omissions and failed persistence can leave gaps. Internal coverage and non-token counters stay in the ledger and are not added to this wire shape without a separate SDK contract update. - `requests` integer: Completed LLM requests, tool-internal ones included. - `input_tokens` integer: Prompt tokens across every request, cached ones included. - `output_tokens` integer: Completion tokens across every request. - `cached_input_tokens` integer: The share of input_tokens served from a provider prompt cache — billed at a reduced rate, so it is reported separately rather than subtracted. - `by_model` ModelTokenUsage[]: The same spend per model that served it, highest first. - `model` string, required: Model identifier as the provider reported it, or as the caller asked for it. - `requests` integer: Observed provider attempts, including explicitly recorded failures. - `input_tokens` integer: Prompt tokens sent to this model, cached ones included. - `output_tokens` integer: Completion tokens this model generated. - `cached_input_tokens` integer: The share of input_tokens served from the provider's prompt cache — billed at a reduced rate, so pricing needs it separated out rather than subtracted. - `grounding_job_ids` string[], nullable: Ground jobs planned for this search's evidences. Empty when postprocessing is disabled for this caller by deployment policy, explicitly disabled for the run, or no evidence is groundable. Absent on older results. When empty or absent, callers may POST /v1/ground explicitly to locate quotes. - QaFileResult: One qa-file run, stored whole so the answer can be reopened. Every field past ``exhausted`` arrived with job-backed history; rows written before it carry only the two receipt fields and still validate, so nothing needs backfilling. A reopened run answers the same question over the same scope: ``scope_path`` and ``scope_component`` are what the caller asked about, not where the answer came from. - `result_type` 'qa_file' - `steps_used` integer - `exhausted` boolean: The agent's step budget ran out before it completed an answer. A successful run, not a failure. - `answer` string, nullable: The prose the run returned. Null only on a pre-history row. - `structured_answer` unknown - `engine` 'recursive_llm' | 'vision' | 'agent', nullable - `scope_path` string, nullable: The uploaded file the question was asked about. - `scope_component` string, nullable: The component (tab / section) the ask was narrowed to. - `citations` Evidence[] - `file_id` string, uuid, required - `path` string, required - `locator` union: Where the snippet sits, when the producer located it. None means the citation is component-level: ground the snippet against path (sheet=component for spreadsheets) to place it. - TextRange: A character span in a derivative's text, with the page(s) it falls on. ``pages`` is every page the span overlaps — a chunk that straddles a page marker belongs to both, and a reader handed only the first would miss the part of the span that carries the match. ``page`` is the first of them, kept because most producers and consumers only ever deal in one page. - … - VisualRegion - … - SpreadsheetRange - … - JsonlRecord - … - JsonPointer: An RFC 6901 pointer into a JSON source; an empty string means the root. - … - AudioRange - … - RowRange: A 0-based inclusive row run on a parquet table. - … - `page` integer, nullable: The 1-based page the producer attributed the snippet to when it produced no locator; None when unknown or when the locator already carries the page. - `relevance_score` number, required - `snippet` string, required - `why` string, required: Which retrieval leg matched, or which graph path led here. - `component` string, nullable: Public component of the hit, in the vocabulary file-metadata lists and qa-file/read-file accept as component= (tab name for spreadsheets, section for split documents); None for a single-component file or when attribution is unavailable. - `sql_table` string, nullable: The run-sql table name holding the hit's component as rows (a spreadsheet tab's table, or a document's printed long tables); None when the component is not a table or the producer does not say. - `line_start` integer, nullable: First line (1-based) of the hit in the text read-file returns for path and component; None when the producer did not place the hit in lines. - `line_end` integer, nullable: Last line (1-based, inclusive) of the hit, counted like line_start; None with it. - `unavailable` UnavailableTable[] - `path` string, required - `error` string, required - `error_kind` 'conversion_rejected' | 'conversion_failed' | 'profile_rejected' | 'profile_failed', nullable - `timed_out` boolean: A guard fired before the engine answered. The body holds the partial-answer wording, not a failure. - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - QaTablesResult: One query-tables run, stored whole so the answer can be reopened. As with :class:`QaFileResult`, everything past ``exhausted`` arrived with job-backed history and is optional, so receipt-only rows still validate. Both lanes land in this one shape: the SQL lane fills ``tables`` and ``result_files``, the agent lane fills ``answer`` and ``citations`` only. - `result_type` 'qa_tables' - `steps_used` integer - `exhausted` boolean: The agent's step budget ran out before it completed an answer. A successful run, not a failure. - `answer` string, nullable: The prose the run returned. Null only on a pre-history row. - `structured_answer` unknown - `error` string, nullable: The engine's own reported trouble on an otherwise 200 run. - `timed_out` boolean - `source_paths` string[]: The table selections the question was asked over. - `source_components` string[]: The named tabs among those selections. - `citations` Evidence[] - `file_id` string, uuid, required - `path` string, required - `locator` union: Where the snippet sits, when the producer located it. None means the citation is component-level: ground the snippet against path (sheet=component for spreadsheets) to place it. - TextRange: A character span in a derivative's text, with the page(s) it falls on. ``pages`` is every page the span overlaps — a chunk that straddles a page marker belongs to both, and a reader handed only the first would miss the part of the span that carries the match. ``page`` is the first of them, kept because most producers and consumers only ever deal in one page. - … - VisualRegion - … - SpreadsheetRange - … - JsonlRecord - … - JsonPointer: An RFC 6901 pointer into a JSON source; an empty string means the root. - … - AudioRange - … - RowRange: A 0-based inclusive row run on a parquet table. - … - `page` integer, nullable: The 1-based page the producer attributed the snippet to when it produced no locator; None when unknown or when the locator already carries the page. - `relevance_score` number, required - `snippet` string, required - `why` string, required: Which retrieval leg matched, or which graph path led here. - `component` string, nullable: Public component of the hit, in the vocabulary file-metadata lists and qa-file/read-file accept as component= (tab name for spreadsheets, section for split documents); None for a single-component file or when attribution is unavailable. - `sql_table` string, nullable: The run-sql table name holding the hit's component as rows (a spreadsheet tab's table, or a document's printed long tables); None when the component is not a table or the producer does not say. - `line_start` integer, nullable: First line (1-based) of the hit in the text read-file returns for path and component; None when the producer did not place the hit in lines. - `line_end` integer, nullable: Last line (1-based, inclusive) of the hit, counted like line_start; None with it. - `tables` QueryTablePreview[] - `path` string, nullable - `handle` string, required - `row_count` integer, required - `columns` QueryTableColumn[] - `name` string, required - `data_type` string, required - `rows` object[] - `preview_truncated` boolean - `result_files` QaTableResultFile[] - `file_id` string, uuid, required - `handle` string, required - `path` string, required - `file_name` string, required - `format` 'parquet' - `row_count` integer, required - `sql` string, required - `source_paths` string[] - `grounding` TableQueryGrounding: One SQL query executed against the caller's tables while answering. The grounding behind a computed evidence: when the agent answers a count/sum/join question it runs a SQL agent over the uploaded tables, and this is the receipt — the query text and a bounded preview of what it returned. Attached to the evidence it grounds rather than published globally, so a computed figure and its computation travel together. ``source_paths`` name uploaded files, resolved server-side through the caller's access gate exactly like ``source_path`` on the evidence itself. - `sql` string, required - `supports_answer` boolean: False for exploratory SQL the tables engine ran but did not mark as part of the answer's calculation trail. - `result_id` string, nullable: Stable identity of the stored query result behind this receipt. Lets the grounding-rows endpoint replay this exact query for matched-row pages beyond the regions' inline runs. - `source_paths` string[]: The uploaded table files this query read — directly, or through a prior result it built on — e.g. 'planning/FS GF Custom.xlsx'. - `row_count` integer: Rows in the query's full result, not in the preview below. - `columns` TableQueryColumn[] - … - `rows` object[]: Leading result rows, values rendered as text — a bounded preview, never the full result. - … - `preview_truncated` boolean: Whether the preview cut rows or columns. - `verified` boolean: True when at least one claim behind this query passed mechanical verification against the source data. Independent of 'regions': a source without an addressable grid verifies but cannot be pointed at, so an empty 'regions' never means unverified. - `regions` union[]: Original-file coordinates for the verified claims whose source file has an addressable grid. - … - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Capture-time provenance status behind this query's regions. 'exact': the exact-provenance sidecar proved every row the query read, so its 'provenance'-basis regions are trustworthy (source regions may be broader than the minimal contributing set when grounding_reason carries a 'regions_broad:…' qualifier). 'unavailable': no exact proof could be captured (a legacy result, or a statement shape the capturer cannot instrument) — no 'provenance'-basis regions are attached, never a guessed whole-table span. 'zero_result': the query matched no rows, so there is nothing to ground. None on legacy payloads and on a query with no unclaimed table left to ground. - `grounding_reason` string, nullable: Qualification on grounding_status, when present. Set for 'unavailable' (explains why proof was not possible) and for 'exact' when capture succeeded but the source regions are broader than the minimal contributing set (e.g. 'regions_broad:narrowing_specs_unavailable'). None when grounding is fully exact or absent. - `download_url` string, nullable: Minted on read; null when the artifact is gone. - `preview_url` string, nullable: Minted on read; null when the artifact is gone. - `download_url_expires_at` string, date-time, nullable - `result_materialization_error` string, nullable - `unavailable` UnavailableTable[] - `path` string, required - `error` string, required - `error_kind` 'conversion_rejected' | 'conversion_failed' | 'profile_rejected' | 'profile_failed', nullable - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - FilteredSearchResult: The typed outcome of one filtered-search execution (or one page of it). ``exhaustive`` is the coarse completeness signal: when it is false, returned matches are valid, but "all"-style claims, ``total_matches`` as a census, and zero-match conclusions are not guaranteed. It is scope-wide and all-or-nothing, so it cannot say *what* was incomplete; ``field_readability`` is its per-field companion, naming the filtered fields the extraction could not fully read — the difference between "no component matched" and "the column you filtered on was largely unreadable". Pagination is LIVE — each page re-executes against the current catalog, so concurrent ingestion, deletion, or relabeling may shift later pages (rows can repeat or be skipped across page boundaries); ``catalog_drifted`` says the scope changed since the query was first validated. - `result_type` 'filtered_search' - `result_unit` 'source' | 'component' | 'entity' | 'entry': The unit used for rows, totals, top-N and pagination. New searches consistently return catalog entries with their established identities. Legacy units remain readable. - `columns` CatalogColumnDescriptor[] - `field` string, required - `kind` 'text' | 'date' | 'money' | 'number' | 'boolean', required - `description` string - `repeated` boolean: Several values may exist per row (parties, signatories). - `filtered` boolean: The published query filtered on this column — or ranked by it under a top-N LIMIT, where ranking decides membership (server-extracted from the SQL, never model-authored). These are the values the matches hinge on, and the first cells worth grounding against their source documents. - `requested` boolean: The user requested this output field; missing values do not exclude a match. - `rows` FilteredSearchRow[] - `component` string, required: Public component name — the tab or document section, matching the component= argument of the file tools (qa-file, read-file, query-tables). Several document rows can share one section name; page_start/page_end distinguish them. A media row's name is the recording stem, display-only (file tools take the whole file). - `component_kind` 'document' | 'sheet' | 'media', required: The representation containing these observations. - `document_type` string, nullable: The profiled document type of this component. - `category` string, nullable: The component's primary taxonomy category. - `subcategory` string, nullable: The component's primary taxonomy subcategory. - `page_start` integer, nullable: First source page containing the component. - `page_end` integer, nullable: Last source page containing the component. - `summary` string: A description of the component's contents. - `entity_id` string, nullable: The printed identifier of the matching entity within a register. - `source_row` integer, nullable: The native sheet row containing this entity's facts. - `cells` FilteredSearchCell[]: Typed observations belonging to this component. - `field` string, required - `status` 'found' | 'not_found' | 'ambiguous' | 'unexamined', required - `value` union - … - `item_index` integer: Position for repeated fields; 0 for scalars. - `citation` Citation: Where an extracted value was found, with optional quoted source text. - … - `native_raw` string, nullable: The stored native cell value, before display formatting or rounding. - `native_display` string, nullable: The source cell's formatted display, when available, kept separately from its typed value. - `content_matches` ContentConditionMatch[]: Content criteria this row satisfied, with observed values and the source passages used to verify them. - `condition` string, required: The content condition evaluated after catalog filtering. - `value` string, nullable: Observed source value supporting the match, when available as a short value. - `evidences` ContentEvidence[], required: Source passages supporting this row's satisfaction of the condition. - … - `source_path` string, required: The uploaded file the result belongs to. - `source_file_id` string, uuid, required: Stable identity of the uploaded source file. - `entry_id` string, uuid, nullable: Catalog entry identity, independent of query wording, filtering and rank. Supporting profile records share an established structural identity; incomplete identities can change on catalog rebuild. Null on legacy units. - `components` FilteredSearchComponent[]: Supporting records grouped into this result, in query order, with their separate values and evidence. The row's component fields mirror the first record for display. Empty when no grouping was needed or on older results. - `component` string, required: Public component name — the tab or document section, matching the component= argument of the file tools (qa-file, read-file, query-tables). Several document rows can share one section name; page_start/page_end distinguish them. A media row's name is the recording stem, display-only (file tools take the whole file). - `component_kind` 'document' | 'sheet' | 'media', required: The representation containing these observations. - `document_type` string, nullable: The profiled document type of this component. - `category` string, nullable: The component's primary taxonomy category. - `subcategory` string, nullable: The component's primary taxonomy subcategory. - `page_start` integer, nullable: First source page containing the component. - `page_end` integer, nullable: Last source page containing the component. - `summary` string: A description of the component's contents. - `entity_id` string, nullable: The printed identifier of the matching entity within a register. - `source_row` integer, nullable: The native sheet row containing this entity's facts. - `cells` FilteredSearchCell[]: Typed observations belonging to this component. - … - `content_matches` ContentConditionMatch[]: Content criteria this row satisfied, with observed values and the source passages used to verify them. - … - `content_verification` ContentVerificationSummary: Coverage of the bounded content check, separate from catalog coverage. - `condition` string, required: The content condition checked on catalog-selected candidates. - `candidates` integer, required: Catalog candidates considered by the cited content check. - `unverified_candidates` integer, required: Candidates whose condition could neither be established nor ruled out, including bounds or unavailable evidence. These records are excluded from confirmed matches, not treated as non-matches. - `total_matches` integer: Confirmed matches in result_unit, before any page or top-N cut. - `total_files` integer, nullable: Distinct source files supporting the confirmed matches before any page or top-N cut. Null for older results or when no authoritative selection was executed. Subject to the same completeness as total_matches. - `next_cursor` string, nullable: Opaque cursor for the next page — POST it back as {type: 'page', cursor}. Null on the last page. - `exhaustive` boolean: True only when every eligible component was completely cataloged and evaluated — the scope-wide completeness signal. False whenever coverage is partial or a residual content condition was applied. - `truncated` boolean: A structural cap degraded this result; matches shown remain valid. - `executed_at` string, date-time, nullable: When this page's snapshot was read. - `catalog_drifted` boolean: The catalog changed since the query was validated. - `applied_query` string, nullable: Server-rendered display form of the published query. - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - `clarification` string, nullable: Non-null exactly when the run asked a clarifying question instead of executing — only possible when the initial query set `allow_clarification`: no rows, no applied_query, exhaustive false. Filtered search keeps no session; answer it by issuing a new initial query. - `content_evidences` ContentEvidence[]: Residual content condition passages, server-verified; present only on residual queries. - `source_path` string, required - `source_file_id` string, uuid, required - `component` string, nullable - `page` integer, nullable - `a1_range` string, nullable: The exact native cell or range containing this quotation, within component. - `quote` string, required - `evidences` SearchEvidence[]: Referent-resolution evidence: the file passages that turned a role or relative referent in the query ('the CEO') into the concrete filter value the published query uses. Agent-cited, then resolved server-side to the caller's own uploaded file exactly like search evidence — an entry that cannot be resolved to a visible file is dropped, never published. Distinct from content_evidences, which are server-verified residual matches. Empty on pure catalog queries. - `source_path` string, required: The uploaded file the quote belongs to, e.g. 'reports/policy.pdf'. This is the file to ground the quote against. - `source_file_id` string, uuid, nullable: The id of the file at source_path, resolved server-side. Always set on newly finalized results; null only on results stored before unresolvable citations were dropped. - `page` integer, nullable: 1-based page number, when the agent saw one. - `component` string, nullable: Public component of the file the quote came from — the tab name for a spreadsheet, the section for a split document; the same vocabulary file-metadata lists. Pass it as the ground target's sheet when grounding a spreadsheet quote. None for a single-component file or when attribution was unavailable. - `quote` string, required: The key passage, as retrieved from the file. - `passages` string[]: Contiguous pieces of the source file that quote was stitched from, in the file's own text. Ground each piece as its own target when this list is present, with max_matches 2. A piece that returns two matches repeats in the file, so which copy the quote used is unknown. A ' | ' marks a table cell boundary added by the check. Replace it with a space before grounding. Filled only for PDF, Word and PowerPoint sources that Ground reads from the PDF text layer. Absent when quote is already one contiguous passage, could not be checked, or could not be verified. - `relevance` string: Deprecated: empty on new results, where `reasoning` says how the evidences support the answer. - `queries` TableQueryGrounding[]: The SQL the run executed over this evidence's table, with a bounded preview of each result — server-recorded from the run's tables engine, never model-authored. Attached whenever the run queried the cited table (or the row extraction of the same spreadsheet tab), so a verbatim quote from a queried sheet carries the computation trail alongside it; empty when the run never queried the cited file's tables. - `sql` string, required - `supports_answer` boolean: False for exploratory SQL the tables engine ran but did not mark as part of the answer's calculation trail. - `result_id` string, nullable: Stable identity of the stored query result behind this receipt. Lets the grounding-rows endpoint replay this exact query for matched-row pages beyond the regions' inline runs. - `source_paths` string[]: The uploaded table files this query read — directly, or through a prior result it built on — e.g. 'planning/FS GF Custom.xlsx'. - `row_count` integer: Rows in the query's full result, not in the preview below. - `columns` TableQueryColumn[] - … - `rows` object[]: Leading result rows, values rendered as text — a bounded preview, never the full result. - … - `preview_truncated` boolean: Whether the preview cut rows or columns. - `verified` boolean: True when at least one claim behind this query passed mechanical verification against the source data. Independent of 'regions': a source without an addressable grid verifies but cannot be pointed at, so an empty 'regions' never means unverified. - `regions` union[]: Original-file coordinates for the verified claims whose source file has an addressable grid. - … - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Capture-time provenance status behind this query's regions. 'exact': the exact-provenance sidecar proved every row the query read, so its 'provenance'-basis regions are trustworthy (source regions may be broader than the minimal contributing set when grounding_reason carries a 'regions_broad:…' qualifier). 'unavailable': no exact proof could be captured (a legacy result, or a statement shape the capturer cannot instrument) — no 'provenance'-basis regions are attached, never a guessed whole-table span. 'zero_result': the query matched no rows, so there is nothing to ground. None on legacy payloads and on a query with no unclaimed table left to ground. - `grounding_reason` string, nullable: Qualification on grounding_status, when present. Set for 'unavailable' (explains why proof was not possible) and for 'exact' when capture succeeded but the source regions are broader than the minimal contributing set (e.g. 'regions_broad:narrowing_specs_unavailable'). None when grounding is fully exact or absent. - `derivation` DerivationTrace: The answer's computation DAG when evidence is derived rather than extracted. - `steps` DerivationStep[] - … - `field_readability` FieldReadability[]: Filtered fields the extraction could not fully read, server-computed. An empty list is an answer — every field the query filtered on was fully readable — rather than an omission. - `field` string, required: The extracted field the query filtered on. - `in_scope` integer, required: Components in scope whose document type carries this field. - `readable` integer, required: Of those, how many had a resolved value the predicate could evaluate. - `coverage` Coverage: What the access gate withheld, in counts and label names only. Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request. - `restricted_candidates` integer - `labels_required` string[]: Which labels would have been needed to see the withheld candidates. - `request_access_hint` string, nullable - `tool_calls` ToolCallTrace[] - `tool` string, required - `arguments_digest` string, required - `hits` integer, required - `duration_ms` integer, required - `steps_used` integer - `exhausted` boolean: Step budget hit before the agent finished. A success, not a failure. - `candidates_seen` integer - JetResult: The result of one journal-entry-testing run (``JobKind.JE_TESTING``). Shape-compatible with :class:`IntelligentSearchResult` for the retrieval core — evidences, reasoning, answer, the tool-call trace, the session handle, usage and exhaustion all mean exactly what they mean there — plus ``sql_receipts``: the statements behind the answer. ``figures`` is the answer's checkable half: one entry per criterion, each naming the receipts its figures are readable out of. There is no ``coverage`` block — v1 runs on tables the caller selected, and an honest coverage number needs an orientation pass that reports what was *not* selected. - `result_type` 'je_testing' - `answer` string, nullable: The direct, grounded answer to the request. Null only on a run that exhausted its budget before authoring one, or that asked `clarification_questions` instead. - `clarification` string, nullable: The run's clarifying questions as plain text, instead of an answer. Only ever set when the request carried `allow_clarification` and the run needed the user's input to go on; `answer` is null and `evidences` empty alongside it. The same questions, structured, are in `clarification_questions`. - `clarification_questions` ClarifyingQuestion[], nullable: The questions behind `clarification`, at most 2, each with up to 4 suggested answers. Answer them with a follow-up on `session_id` that repeats the query and carries `clarification_answers` (one entry per question, a null answer skips it), or with any follow-up query in your own words. Null on every run that answered. - `question` string, required: The question, as the run asked it. - `options` string[]: Suggested answers, most likely first. Never exhaustive: the user may always answer in their own words, so no option stands for 'Other'. Empty when the run offered none. - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - `population_statement` string, nullable: The population every figure was computed over — file, period, layer, status, basis, grain — in the run's own words. Null only on a run that never authored an answer. - `figures` JetFigure[]: One entry per criterion tested, each linked to the receipts its figures are readable out of. Empty on a run that answered without testing anything, or that exhausted its budget first. - `criterion` string, required: What was tested, in the caller's terms. - `definition` string, required: The definition it was tested under: which column and values encoded the term, which clock, which basis, which threshold and where it came from. - `spec_id` string, required: The run's committed TestSpec this figure was computed under. - `population` integer, required: The denominator — rows at this test's grain that the criterion ran over. - `count` integer, required: Members of the population that met the criterion. - `value` string, nullable: The exceptions' value as text, so a decimal survives the wire. Null for a count-only criterion. - `result_ids` string[]: `sql_receipts[].result_id` of every statement this figure is readable out of. - `exception_listing_result_id` string, nullable: The receipt that lists the exceptions themselves, when one was produced. - `band_group` string, nullable: Set when this figure is one band of a family that partitions a population — the same name on every band of the family, whose counts sum to that population. - `cannot_be_performed` boolean: The workspace does not hold the material this criterion needs. `result_ids` then name the probes that establish the absence rather than the figures. - `breakdown` JetBreakdown: The tabular result behind one figure, attached by the server. What a caller asking "by FSLI and month" or "top 10 preparers" wanted, in the shape the question implies. The rows are NOT model-authored and never were: they are the cited receipt's own result, stringified and capped here, attached at finalize from :class:`SqlReceipt` rows the run already published. That is the whole design — a figure's table costs the model no output tokens and cannot carry a cell no statement returned — and it is why there is no reshaping either: the receipt's shape IS the breakdown, so a matrix the SQL never grouped by month is a wrong statement rather than a rendering problem. ``result_id`` names the receipt the rows came from, which is always one of the figure's own citations — either on ``result_ids`` or its ``exception_listing_result_id``, the two id sets the console makes openable — so the breakdown is a convenience over the payload's own working, never a second source of truth, and a reader who wants the statement, the whole bounded result or its row provenance follows that id. (When the model names a listing it did not also list in ``receipt_ids``, that id reaches the figure through ``exception_listing_result_id`` rather than ``result_ids``; both render as receipt buttons, so the table stays one click away either way.) - `columns` string[]: Column names, in the statement's own result order. - `rows` array[]: Rows in receipt order, cells as text so a decimal, a date and a NULL all survive the wire. At most 200; a longer result sets `truncated` and stays whole on its receipt. - … - `truncated` boolean: Whether rows were cut — either by this table's own cap or already on the receipt it came from. A capped breakdown is never read as the complete listing. - `result_id` string, required: `sql_receipts[].result_id` of the statement these rows are. - `criteria` JetCriterionOutcome[]: Every requested test and its final disposition, including tests that never reached binding, measurement, or a published figure. Empty only on results stored before this checklist existed. - `criterion_id` string, required: Stable short id for this requested test. Its TestSpec and published figure use the same id. - `description` string, required: The requested test in the caller's terms, without an invented conclusion. - `status` 'performed' | 'cannot_be_performed' | 'incomplete', required: Whether the test produced a finding, proved it could not be performed, or remained incomplete. - `spec_id` string, nullable: The committed TestSpec id and matching `figures[].spec_id`. Null when setup never reached a spec. - `blocker` 'binding_unresolved' | 'measurement_failed' | 'missing_finding' | 'population_incomplete' | 'context_exhausted' | 'missing_business_parameter' | 'methodology_unresolved' | 'finding_unverified', nullable: Why an incomplete test did not finish, including reasons newer than the three `incomplete_reason` keeps to. Null for performed and cannot-be-performed tests. - `incomplete_reason` 'binding_unresolved' | 'measurement_failed' | 'missing_finding', nullable: `blocker` in the three values older SDKs accept: `population_incomplete` and `finding_unverified` read as `measurement_failed`, and every other newer blocker as `missing_finding`. Read `blocker` for the full reason. - `missing_parameters` string[]: Policy inputs this test was missing. Set only when `blocker` is `missing_business_parameter` or `methodology_unresolved`; empty otherwise. - `discrepancies` string[]: Where the data contradicted the request's premise or a figure it stated. Empty when nothing did — the run is asked for this explicitly, so an empty list is an answer rather than an omission. - `reasoning` string, nullable: How the receipted statements chain together into the answer. - `evidences` SearchEvidence[]: The material the answer cites, each resolved to the caller's own uploaded file. - `source_path` string, required: The uploaded file the quote belongs to, e.g. 'reports/policy.pdf'. This is the file to ground the quote against. - `source_file_id` string, uuid, nullable: The id of the file at source_path, resolved server-side. Always set on newly finalized results; null only on results stored before unresolvable citations were dropped. - `page` integer, nullable: 1-based page number, when the agent saw one. - `component` string, nullable: Public component of the file the quote came from — the tab name for a spreadsheet, the section for a split document; the same vocabulary file-metadata lists. Pass it as the ground target's sheet when grounding a spreadsheet quote. None for a single-component file or when attribution was unavailable. - `quote` string, required: The key passage, as retrieved from the file. - `passages` string[]: Contiguous pieces of the source file that quote was stitched from, in the file's own text. Ground each piece as its own target when this list is present, with max_matches 2. A piece that returns two matches repeats in the file, so which copy the quote used is unknown. A ' | ' marks a table cell boundary added by the check. Replace it with a space before grounding. Filled only for PDF, Word and PowerPoint sources that Ground reads from the PDF text layer. Absent when quote is already one contiguous passage, could not be checked, or could not be verified. - `relevance` string: Deprecated: empty on new results, where `reasoning` says how the evidences support the answer. - `queries` TableQueryGrounding[]: The SQL the run executed over this evidence's table, with a bounded preview of each result — server-recorded from the run's tables engine, never model-authored. Attached whenever the run queried the cited table (or the row extraction of the same spreadsheet tab), so a verbatim quote from a queried sheet carries the computation trail alongside it; empty when the run never queried the cited file's tables. - `sql` string, required - `supports_answer` boolean: False for exploratory SQL the tables engine ran but did not mark as part of the answer's calculation trail. - `result_id` string, nullable: Stable identity of the stored query result behind this receipt. Lets the grounding-rows endpoint replay this exact query for matched-row pages beyond the regions' inline runs. - `source_paths` string[]: The uploaded table files this query read — directly, or through a prior result it built on — e.g. 'planning/FS GF Custom.xlsx'. - `row_count` integer: Rows in the query's full result, not in the preview below. - `columns` TableQueryColumn[] - … - `rows` object[]: Leading result rows, values rendered as text — a bounded preview, never the full result. - … - `preview_truncated` boolean: Whether the preview cut rows or columns. - `verified` boolean: True when at least one claim behind this query passed mechanical verification against the source data. Independent of 'regions': a source without an addressable grid verifies but cannot be pointed at, so an empty 'regions' never means unverified. - `regions` union[]: Original-file coordinates for the verified claims whose source file has an addressable grid. - … - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Capture-time provenance status behind this query's regions. 'exact': the exact-provenance sidecar proved every row the query read, so its 'provenance'-basis regions are trustworthy (source regions may be broader than the minimal contributing set when grounding_reason carries a 'regions_broad:…' qualifier). 'unavailable': no exact proof could be captured (a legacy result, or a statement shape the capturer cannot instrument) — no 'provenance'-basis regions are attached, never a guessed whole-table span. 'zero_result': the query matched no rows, so there is nothing to ground. None on legacy payloads and on a query with no unclaimed table left to ground. - `grounding_reason` string, nullable: Qualification on grounding_status, when present. Set for 'unavailable' (explains why proof was not possible) and for 'exact' when capture succeeded but the source regions are broader than the minimal contributing set (e.g. 'regions_broad:narrowing_specs_unavailable'). None when grounding is fully exact or absent. - `derivation` DerivationTrace: The answer's computation DAG when evidence is derived rather than extracted. - `steps` DerivationStep[] - … - `sql_receipts` SqlReceipt[]: Every statement the run executed, in execution order — the answer's working. - `result_id` string, required: Stable per-run identity of this statement, in execution order (e.g. 'sql_3'). - `sql` string, required: The statement as executed, verbatim. - `handle` string, nullable: Content-addressed key of this statement's stored result, derived from the statement text. Server-side identity: it is what lets the run's own publication find the stored result and its capture-time provenance, and it is NOT an address an agent may query or chain from — `result_id` is the identity the caller and the row pager use. Null on a run that stored no result for the statement. A `cat_` handle names an exploratory document-catalog query: it stores no result beyond the rows carried here. - `table_bindings` SqlTableBinding[]: The tables this statement registered, each with the view name it was referenced by. - `path` string, required: The uploaded table file this view read, e.g. 'ledger/journal.xlsx'. - `component` string, nullable: The source worksheet, including when selected alone. Null for a direct upload or a historical unnamed tab. - `table_name` string, required: The view name the SQL referenced this table by, for THIS run. - `source_sha256` string, nullable: SHA-256 identity of the ingested source generation behind this table binding. - `replay` SqlReplayReceipt: Immutable inputs and engine identity for independent result recomputation. - `schema_version` 1 - `kind` 'aggregate' | 'rowset', required: The verification lane appropriate for this statement. - `engine` 'duckdb', required: The query engine that executed the statement. - `engine_version` string, required: The query-engine version that executed the statement. - `engine_threads` integer, required: DuckDB thread count used for this execution. - `normalized_sql` string, required: The normalized single SELECT statement to execute during independent replay. - `sql_sha256` string, required: SHA-256 identity of the normalized statement. - `logical_plan_sha256` string, required: SHA-256 identity of the parser tree after source-position fields are removed. - `catalog_sha256` string, required: SHA-256 identity of the ordered source bindings used by this statement. - `result_artifact_sha256` string, required: SHA-256 identity of the complete retained result Parquet produced by the service. - `result_data_sha256` string, required: SHA-256 identity of the complete typed result rows. - `result_digest_version` string, required: Versioned Arrow serialization scheme used for the typed-result identity. - `result_dependencies` string[]: Earlier retained result handles read by this statement, in deterministic order. - `columns` string[]: Result column names, in result order. - `rows` object[]: Result rows, values rendered as text so a decimal, a date and a NULL all survive the wire. - `row_count` integer: Rows carried below — not the statement's unbounded result size. - `result_row_count` integer: Rows in the statement's complete stored result. Equal to `row_count` when nothing was cut; the number a total or an exception count must be read from when `truncated` is set. - `truncated` boolean: Whether rows past the stored cap were cut from this receipt. - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Whether this statement's stored result already carried proof of which source rows it read when the receipt was recorded. 'exact' means it did; 'unavailable' means the proof could not be read; 'zero_result' means there were no rows to ground. Null when nothing had been captured yet — the ordinary case for a lane that captures at publication time, so this is a record of what execution happened to know and NOT a prediction of whether the receipt can be grounded. What was actually proven is published as `grounding_status` on the matching evidence query, beside the `regions` it earned. - `views_used` string[]: Session views registered when this statement ran, in definition order — the registry snapshot it executed under. A statement naming a view is replayable only against these, which is what makes named views admissible where chaining a previous call's result handle is not. - `saved_as` string, nullable: The session view this statement was registered as, when it was. Every name in another receipt's ``views_used`` appears here on exactly one receipt, so the run's receipts define every view they cite. - `view_sql` string, nullable: The definition registered under `saved_as`, when it is not this statement itself. Null on an ordinary `save_as`, where `sql` IS the definition. Set by `build_journal_view`, which registers the per-journal frame and runs a bounded probe over it rather than materializing the whole frame — so the definition every later `views_used` refers to is still published by exactly one receipt. - `warnings` string[]: Pre-execution lint notes attached to this statement — non-blocking, and published as part of its working. - `executor` string, nullable: The named executor that generated this statement (`reconcile_movement`, `test_timing`, `find_duplicates`, `field_completeness`, `journal_balance`), when one did, `custom_sql` for a statement the fixed-pipeline engine authored under its escape, or `ledger_understanding` for the ledger-understanding census's own statement, which ran before this run and is cited rather than re-run. Null when no named generator produced it — a population count, an absence probe, or SQL the agent wrote itself. Both engines use the same words here. - `parameters` object: The executor's resolved call, flattened to text — the clock and its true grain, the window's day offsets, the signature, the tolerance, the population. Empty on a statement no executor generated. This is what makes a figure trace to a named, parameterized computation rather than to SQL alone. - `binding` LedgerBindingWire: The definitional layer a run committed, echoed for the caller to read. This is the answer to "on what definitions does this figure rest" — the question the prose relay of the old playbook could not answer, and the reason the binding is a validated artifact rather than a paragraph. Every pin was checked against the tables' own profiles before the run was allowed to compute anything: the columns exist with compatible types, the period roles partition the observed domain, each clock's declared grain matches its column, and every encoding value occurs in its column. Published as flat slot listings rather than as a mirror of the internal model's tree. Two reasons, both practical: a reader wants "which column is the approval clock" answered in one place rather than by walking a nested object, and a slot the design adds later becomes another row here instead of a change to this contract. - `tables` BoundTable[] - `role` string, required: The slot it fills: 'journal_lines', 'journal_headers', 'trial_balance', …. - `path` string, required: The uploaded file, e.g. 'ledger/journal.xlsx'. - `component` string, nullable: The tab, when the file contributed more than one table. - `table_name` string, required: The view name this run's SQL referenced it by. - `policy_sheets` string[]: Documents the run treated as settling parameters (a sequence policy, a topside register). - `columns` BoundColumn[]: Every column pinned to a slot, in slot order. - `slot` string, required: The slot this column fills, dotted: 'journal_key', 'clocks.created', 'amount_bases[reporting].debit', 'accounts.fsli'. - `path` string, required - `component` string, nullable - `table_name` string, required - `column` string, required - `detail` string, nullable: What the slot additionally states about this column — a clock's true grain, that a basis is the one the trial balance ties to, what a calendar date means. - `periods` BoundPeriod[]: The period domain, in period order, with roles. - `value` string, required - `role` string, required: 'opening', 'month', 'year_end_adj' or 'total_row'. - `value_sets` BoundValueSet[]: Encoding candidates and layer memberships. More than one entry under 'encodings.manual' means the run kept both readings and resolved them per test. - `slot` string, required: 'encodings.posted', 'encodings.manual', 'layers.book', …. - `name` string, required: The candidate's name, as a test spec cites it. - `path` string, required - `component` string, nullable - `table_name` string, required - `column` string, required - `values` string[]: The values of that column which mean this. - `note` string: Where this reading came from — a policy sheet, a flag column, a profiled domain. - `notes` string[]: Deviations the run observed while orienting. - `revised_because` string, nullable: Why the binding was replaced mid-run, when it was. Null on a run that bound once. - `tool_calls` ToolCallTrace[]: One entry per tool the run invoked, in execution order — the tool's name, a digest of its arguments, how many results came back, and how long it took. The run's shape, not its content. - `tool` string, required - `arguments_digest` string, required - `hits` integer, required - `duration_ms` integer, required - `steps_used` integer: Legacy procedure-step count retained for compatibility. It is engine-specific and is not a model-request count; agent runs expose completed root-model requests in `agent_usage`. Read it with `exhausted`, which says whether the configured request budget ran out before the run was satisfied. - `exhausted` boolean: Step budget hit before the run was satisfied. A successful response, not a failure. - `degraded` string, nullable: Why this result is degraded, when it is. The run broke before it could finalize an answer but had already computed real working, so what is published is that working — `sql_receipts` and `binding` — with `figures` empty and `answer` saying so. Null on every run that finished normally, exhausted ones included. - `quality` JetQuality: Structured execution-quality reporting for one JE-testing result. Distinguishes a clean, fully evidenced success from a recovered or partially validated one without changing ``ok`` or inventing figures. Contains only check names, tool names, outcome categories, and counts — never prompts, answers, evidence bodies, shell output, or client identifiers. - `status` 'clean' | 'recovered_with_warnings' | 'degraded', required: ``clean`` when nothing was recovered; ``recovered_with_warnings`` when a fail-open check, tool failure, or missing audit artifact was recorded; ``degraded`` when the run salvaged working after a hard failure (see ``JetResult.degraded``). - `validation_warnings` JetValidationWarning[]: Fail-open output checks that passed the answer through after their corrective retry. - `check` 'specs' | 'scope' | 'cycle' | 'grain' | 'basis' | 'absence' | 'bands' | 'pointer' | 'delivery' | 'figures', required: Stable machine-readable name of the fail-open check that was not satisfied. ``specs`` covers two causes: a finding that names no committed test, and a finding computed for a test the run still declared blocked by a missing parameter. - `status` 'failed_open': Always ``failed_open``: the check rejected the answer once, then passed it through. - `tool_failures` JetToolFailure[]: Non-success tool outcomes the agent recovered from, aggregated by tool and category. - `tool` string, required: Tool name that produced the non-success outcome (for example ``run_command``). - `outcome` 'model_retry' | 'command_error' | 'timeout' | 'tool_error', required: Category of the non-success: ``model_retry`` (a call the run corrected: a gate refusal, a rejected argument shape or a validation retry; does not lower `quality.status`), ``command_error`` (non-zero shell exit), ``timeout``, or ``tool_error`` (the tool itself failed, for example a SQL error). - `count` integer, required: How many times this tool×outcome pair occurred in the run. - `missing_artifacts` string[]: Required audit artifact classes absent from a quantitative result (``binding`` and/or ``sql_receipts``). Empty when every finding is ``cannot_be_performed`` or when both artifacts are present. - `retried_checks` string[]: Output-contract check families that cost the answer a model re-emission, whether or not the re-emission repaired them. Attribution only — a retry the model then satisfied is a clean answer, so this does not move ``status``. - `withheld_receipt_figures` integer: How many performed figures were published with no readable receipt id — either the statements behind them are not visible to this caller, or the figure was computed without one. The figures themselves are still returned; this counts the ones whose working cannot be inspected. - `execution_status` 'performed' | 'partially_performed' | 'not_performed', nullable: Whether the run tested what it was asked to test: ``performed`` when every figure was computed, ``partially_performed`` when some criteria could not be, ``not_performed`` when none could. Read it alongside `quality`, which grades how well a performed test went. JE-testing always sets this on a finished run; other JetResult subclasses (deep search) leave it null, as do results stored before the field existed. - `agent_usage` JetAgentUsage: Completed root-agent model requests by session phase. This is intentionally separate from :class:`SearchLlmUsage`: that ledger covers every nested LLM call and token, while this block explains the agent procedure itself. Provider transport attempts are not exposed by the model boundary reliably and are therefore not guessed here. - `execution_requests` integer, required: Completed model requests in normal execution cycles. - `compaction_requests` integer, required: Completed model requests used to summarize compacted history. - `finalization_requests` integer, required: Completed requests in the tool-less recovery finalizer. - `total_requests` integer, required: Sum of execution, compaction, and finalization requests. - `spec_digest` string, nullable: A short fingerprint of what this run committed to TEST — the rows, grain, clock, encoding, thresholds and time window each criterion was pinned to — with the free-text justifications beside those choices excluded. Two runs of the same question carry the same value when they tested the same thing, so an unstable answer can be told apart from an answer to a quietly different question without re-reading either run. Null on a run that committed no test spec, and on other JetResult subclasses. - `session_id` string, uuid, nullable: The conversation this run belongs to. Send it back as the request's `session_id` to ask a follow-up in the same thread. - `usage` SearchLlmUsage: What answering one search query cost in LLM work. Present only when the run was asked to account for itself *and* spend reached its ledger; ``null`` otherwise, so a caller can tell "nothing was measured" from "nothing was spent". An empty ledger publishes ``null`` rather than a zeroed object for that reason: zeros would claim a measured run cost nothing, when what an empty ledger most likely records is accounting that never landed. The totals cover recorded model calls at any depth: the agent's own turns, and the calls the retrieval tools made on its behalf — a document read by the recursive-LLM engine, a scan cracked by the vision engine, a tables question answered by the SQL agent. That is the number a per-query cost figure needs, and it is invariably several times the agent's own turn count. ``by_model`` is the same spend split by the model that served it, because a run legitimately spends on several at different prices — a total alone cannot be turned into money. The totals are the sum of ``by_model`` and are published anyway so the common case needs no arithmetic. Observed retries are included. These public token totals are not a complete cost certificate: provider omissions and failed persistence can leave gaps. Internal coverage and non-token counters stay in the ledger and are not added to this wire shape without a separate SDK contract update. - `requests` integer: Completed LLM requests, tool-internal ones included. - `input_tokens` integer: Prompt tokens across every request, cached ones included. - `output_tokens` integer: Completion tokens across every request. - `cached_input_tokens` integer: The share of input_tokens served from a provider prompt cache — billed at a reduced rate, so it is reported separately rather than subtracted. - `by_model` ModelTokenUsage[]: The same spend per model that served it, highest first. - `model` string, required: Model identifier as the provider reported it, or as the caller asked for it. - `requests` integer: Observed provider attempts, including explicitly recorded failures. - `input_tokens` integer: Prompt tokens sent to this model, cached ones included. - `output_tokens` integer: Completion tokens this model generated. - `cached_input_tokens` integer: The share of input_tokens served from the provider's prompt cache — billed at a reduced rate, so pricing needs it separated out rather than subtracted. - `grounding_job_ids` string[], nullable: Ground jobs planned for this search's evidences. Empty when postprocessing is disabled for this caller by deployment policy, explicitly disabled for the run, or no evidence is groundable. Absent on older results. When empty or absent, callers may POST /v1/ground explicitly to locate quotes. - DeepSearchV2Result: The result of one source-level deep-search run (``JobKind.DEEP_SEARCH_V2``). Field-for-field the JET shape — answer, reasoning, evidences, the run's ``sql_receipts``, the tool-call trace, session handle, usage, exhaustion — under its own discriminator: the two kinds share one agent chassis and one fold, and a second field list here would only be a place for them to drift. On this surface a receipt's ``rows`` are the statement's bounded preview; the full result is retained server-side and re-queryable through the ``res_…`` handle appearing in any statement that pages it. - `result_type` 'deep_search_v2' - `answer` string, nullable: The direct, grounded answer to the request. Null only on a run that exhausted its budget before authoring one, or that asked `clarification_questions` instead. - `clarification` string, nullable: The run's clarifying questions as plain text, instead of an answer. Only ever set when the request carried `allow_clarification` and the run needed the user's input to go on; `answer` is null and `evidences` empty alongside it. The same questions, structured, are in `clarification_questions`. - `clarification_questions` ClarifyingQuestion[], nullable: The questions behind `clarification`, at most 2, each with up to 4 suggested answers. Answer them with a follow-up on `session_id` that repeats the query and carries `clarification_answers` (one entry per question, a null answer skips it), or with any follow-up query in your own words. Null on every run that answered. - `question` string, required: The question, as the run asked it. - `options` string[]: Suggested answers, most likely first. Never exhaustive: the user may always answer in their own words, so no option stands for 'Other'. Empty when the run offered none. - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - `population_statement` string, nullable: The population every figure was computed over — file, period, layer, status, basis, grain — in the run's own words. Null only on a run that never authored an answer. - `figures` JetFigure[]: One entry per criterion tested, each linked to the receipts its figures are readable out of. Empty on a run that answered without testing anything, or that exhausted its budget first. - `criterion` string, required: What was tested, in the caller's terms. - `definition` string, required: The definition it was tested under: which column and values encoded the term, which clock, which basis, which threshold and where it came from. - `spec_id` string, required: The run's committed TestSpec this figure was computed under. - `population` integer, required: The denominator — rows at this test's grain that the criterion ran over. - `count` integer, required: Members of the population that met the criterion. - `value` string, nullable: The exceptions' value as text, so a decimal survives the wire. Null for a count-only criterion. - `result_ids` string[]: `sql_receipts[].result_id` of every statement this figure is readable out of. - `exception_listing_result_id` string, nullable: The receipt that lists the exceptions themselves, when one was produced. - `band_group` string, nullable: Set when this figure is one band of a family that partitions a population — the same name on every band of the family, whose counts sum to that population. - `cannot_be_performed` boolean: The workspace does not hold the material this criterion needs. `result_ids` then name the probes that establish the absence rather than the figures. - `breakdown` JetBreakdown: The tabular result behind one figure, attached by the server. What a caller asking "by FSLI and month" or "top 10 preparers" wanted, in the shape the question implies. The rows are NOT model-authored and never were: they are the cited receipt's own result, stringified and capped here, attached at finalize from :class:`SqlReceipt` rows the run already published. That is the whole design — a figure's table costs the model no output tokens and cannot carry a cell no statement returned — and it is why there is no reshaping either: the receipt's shape IS the breakdown, so a matrix the SQL never grouped by month is a wrong statement rather than a rendering problem. ``result_id`` names the receipt the rows came from, which is always one of the figure's own citations — either on ``result_ids`` or its ``exception_listing_result_id``, the two id sets the console makes openable — so the breakdown is a convenience over the payload's own working, never a second source of truth, and a reader who wants the statement, the whole bounded result or its row provenance follows that id. (When the model names a listing it did not also list in ``receipt_ids``, that id reaches the figure through ``exception_listing_result_id`` rather than ``result_ids``; both render as receipt buttons, so the table stays one click away either way.) - `columns` string[]: Column names, in the statement's own result order. - `rows` array[]: Rows in receipt order, cells as text so a decimal, a date and a NULL all survive the wire. At most 200; a longer result sets `truncated` and stays whole on its receipt. - … - `truncated` boolean: Whether rows were cut — either by this table's own cap or already on the receipt it came from. A capped breakdown is never read as the complete listing. - `result_id` string, required: `sql_receipts[].result_id` of the statement these rows are. - `criteria` JetCriterionOutcome[]: Every requested test and its final disposition, including tests that never reached binding, measurement, or a published figure. Empty only on results stored before this checklist existed. - `criterion_id` string, required: Stable short id for this requested test. Its TestSpec and published figure use the same id. - `description` string, required: The requested test in the caller's terms, without an invented conclusion. - `status` 'performed' | 'cannot_be_performed' | 'incomplete', required: Whether the test produced a finding, proved it could not be performed, or remained incomplete. - `spec_id` string, nullable: The committed TestSpec id and matching `figures[].spec_id`. Null when setup never reached a spec. - `blocker` 'binding_unresolved' | 'measurement_failed' | 'missing_finding' | 'population_incomplete' | 'context_exhausted' | 'missing_business_parameter' | 'methodology_unresolved' | 'finding_unverified', nullable: Why an incomplete test did not finish, including reasons newer than the three `incomplete_reason` keeps to. Null for performed and cannot-be-performed tests. - `incomplete_reason` 'binding_unresolved' | 'measurement_failed' | 'missing_finding', nullable: `blocker` in the three values older SDKs accept: `population_incomplete` and `finding_unverified` read as `measurement_failed`, and every other newer blocker as `missing_finding`. Read `blocker` for the full reason. - `missing_parameters` string[]: Policy inputs this test was missing. Set only when `blocker` is `missing_business_parameter` or `methodology_unresolved`; empty otherwise. - `discrepancies` string[]: Where the data contradicted the request's premise or a figure it stated. Empty when nothing did — the run is asked for this explicitly, so an empty list is an answer rather than an omission. - `reasoning` string, nullable: How the receipted statements chain together into the answer. - `evidences` SearchEvidence[]: The material the answer cites, each resolved to the caller's own uploaded file. - `source_path` string, required: The uploaded file the quote belongs to, e.g. 'reports/policy.pdf'. This is the file to ground the quote against. - `source_file_id` string, uuid, nullable: The id of the file at source_path, resolved server-side. Always set on newly finalized results; null only on results stored before unresolvable citations were dropped. - `page` integer, nullable: 1-based page number, when the agent saw one. - `component` string, nullable: Public component of the file the quote came from — the tab name for a spreadsheet, the section for a split document; the same vocabulary file-metadata lists. Pass it as the ground target's sheet when grounding a spreadsheet quote. None for a single-component file or when attribution was unavailable. - `quote` string, required: The key passage, as retrieved from the file. - `passages` string[]: Contiguous pieces of the source file that quote was stitched from, in the file's own text. Ground each piece as its own target when this list is present, with max_matches 2. A piece that returns two matches repeats in the file, so which copy the quote used is unknown. A ' | ' marks a table cell boundary added by the check. Replace it with a space before grounding. Filled only for PDF, Word and PowerPoint sources that Ground reads from the PDF text layer. Absent when quote is already one contiguous passage, could not be checked, or could not be verified. - `relevance` string: Deprecated: empty on new results, where `reasoning` says how the evidences support the answer. - `queries` TableQueryGrounding[]: The SQL the run executed over this evidence's table, with a bounded preview of each result — server-recorded from the run's tables engine, never model-authored. Attached whenever the run queried the cited table (or the row extraction of the same spreadsheet tab), so a verbatim quote from a queried sheet carries the computation trail alongside it; empty when the run never queried the cited file's tables. - `sql` string, required - `supports_answer` boolean: False for exploratory SQL the tables engine ran but did not mark as part of the answer's calculation trail. - `result_id` string, nullable: Stable identity of the stored query result behind this receipt. Lets the grounding-rows endpoint replay this exact query for matched-row pages beyond the regions' inline runs. - `source_paths` string[]: The uploaded table files this query read — directly, or through a prior result it built on — e.g. 'planning/FS GF Custom.xlsx'. - `row_count` integer: Rows in the query's full result, not in the preview below. - `columns` TableQueryColumn[] - … - `rows` object[]: Leading result rows, values rendered as text — a bounded preview, never the full result. - … - `preview_truncated` boolean: Whether the preview cut rows or columns. - `verified` boolean: True when at least one claim behind this query passed mechanical verification against the source data. Independent of 'regions': a source without an addressable grid verifies but cannot be pointed at, so an empty 'regions' never means unverified. - `regions` union[]: Original-file coordinates for the verified claims whose source file has an addressable grid. - … - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Capture-time provenance status behind this query's regions. 'exact': the exact-provenance sidecar proved every row the query read, so its 'provenance'-basis regions are trustworthy (source regions may be broader than the minimal contributing set when grounding_reason carries a 'regions_broad:…' qualifier). 'unavailable': no exact proof could be captured (a legacy result, or a statement shape the capturer cannot instrument) — no 'provenance'-basis regions are attached, never a guessed whole-table span. 'zero_result': the query matched no rows, so there is nothing to ground. None on legacy payloads and on a query with no unclaimed table left to ground. - `grounding_reason` string, nullable: Qualification on grounding_status, when present. Set for 'unavailable' (explains why proof was not possible) and for 'exact' when capture succeeded but the source regions are broader than the minimal contributing set (e.g. 'regions_broad:narrowing_specs_unavailable'). None when grounding is fully exact or absent. - `derivation` DerivationTrace: The answer's computation DAG when evidence is derived rather than extracted. - `steps` DerivationStep[] - … - `sql_receipts` SqlReceipt[]: Every statement the run executed, in execution order — the answer's working. - `result_id` string, required: Stable per-run identity of this statement, in execution order (e.g. 'sql_3'). - `sql` string, required: The statement as executed, verbatim. - `handle` string, nullable: Content-addressed key of this statement's stored result, derived from the statement text. Server-side identity: it is what lets the run's own publication find the stored result and its capture-time provenance, and it is NOT an address an agent may query or chain from — `result_id` is the identity the caller and the row pager use. Null on a run that stored no result for the statement. A `cat_` handle names an exploratory document-catalog query: it stores no result beyond the rows carried here. - `table_bindings` SqlTableBinding[]: The tables this statement registered, each with the view name it was referenced by. - `path` string, required: The uploaded table file this view read, e.g. 'ledger/journal.xlsx'. - `component` string, nullable: The source worksheet, including when selected alone. Null for a direct upload or a historical unnamed tab. - `table_name` string, required: The view name the SQL referenced this table by, for THIS run. - `source_sha256` string, nullable: SHA-256 identity of the ingested source generation behind this table binding. - `replay` SqlReplayReceipt: Immutable inputs and engine identity for independent result recomputation. - `schema_version` 1 - `kind` 'aggregate' | 'rowset', required: The verification lane appropriate for this statement. - `engine` 'duckdb', required: The query engine that executed the statement. - `engine_version` string, required: The query-engine version that executed the statement. - `engine_threads` integer, required: DuckDB thread count used for this execution. - `normalized_sql` string, required: The normalized single SELECT statement to execute during independent replay. - `sql_sha256` string, required: SHA-256 identity of the normalized statement. - `logical_plan_sha256` string, required: SHA-256 identity of the parser tree after source-position fields are removed. - `catalog_sha256` string, required: SHA-256 identity of the ordered source bindings used by this statement. - `result_artifact_sha256` string, required: SHA-256 identity of the complete retained result Parquet produced by the service. - `result_data_sha256` string, required: SHA-256 identity of the complete typed result rows. - `result_digest_version` string, required: Versioned Arrow serialization scheme used for the typed-result identity. - `result_dependencies` string[]: Earlier retained result handles read by this statement, in deterministic order. - `columns` string[]: Result column names, in result order. - `rows` object[]: Result rows, values rendered as text so a decimal, a date and a NULL all survive the wire. - `row_count` integer: Rows carried below — not the statement's unbounded result size. - `result_row_count` integer: Rows in the statement's complete stored result. Equal to `row_count` when nothing was cut; the number a total or an exception count must be read from when `truncated` is set. - `truncated` boolean: Whether rows past the stored cap were cut from this receipt. - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Whether this statement's stored result already carried proof of which source rows it read when the receipt was recorded. 'exact' means it did; 'unavailable' means the proof could not be read; 'zero_result' means there were no rows to ground. Null when nothing had been captured yet — the ordinary case for a lane that captures at publication time, so this is a record of what execution happened to know and NOT a prediction of whether the receipt can be grounded. What was actually proven is published as `grounding_status` on the matching evidence query, beside the `regions` it earned. - `views_used` string[]: Session views registered when this statement ran, in definition order — the registry snapshot it executed under. A statement naming a view is replayable only against these, which is what makes named views admissible where chaining a previous call's result handle is not. - `saved_as` string, nullable: The session view this statement was registered as, when it was. Every name in another receipt's ``views_used`` appears here on exactly one receipt, so the run's receipts define every view they cite. - `view_sql` string, nullable: The definition registered under `saved_as`, when it is not this statement itself. Null on an ordinary `save_as`, where `sql` IS the definition. Set by `build_journal_view`, which registers the per-journal frame and runs a bounded probe over it rather than materializing the whole frame — so the definition every later `views_used` refers to is still published by exactly one receipt. - `warnings` string[]: Pre-execution lint notes attached to this statement — non-blocking, and published as part of its working. - `executor` string, nullable: The named executor that generated this statement (`reconcile_movement`, `test_timing`, `find_duplicates`, `field_completeness`, `journal_balance`), when one did, `custom_sql` for a statement the fixed-pipeline engine authored under its escape, or `ledger_understanding` for the ledger-understanding census's own statement, which ran before this run and is cited rather than re-run. Null when no named generator produced it — a population count, an absence probe, or SQL the agent wrote itself. Both engines use the same words here. - `parameters` object: The executor's resolved call, flattened to text — the clock and its true grain, the window's day offsets, the signature, the tolerance, the population. Empty on a statement no executor generated. This is what makes a figure trace to a named, parameterized computation rather than to SQL alone. - `binding` LedgerBindingWire: The definitional layer a run committed, echoed for the caller to read. This is the answer to "on what definitions does this figure rest" — the question the prose relay of the old playbook could not answer, and the reason the binding is a validated artifact rather than a paragraph. Every pin was checked against the tables' own profiles before the run was allowed to compute anything: the columns exist with compatible types, the period roles partition the observed domain, each clock's declared grain matches its column, and every encoding value occurs in its column. Published as flat slot listings rather than as a mirror of the internal model's tree. Two reasons, both practical: a reader wants "which column is the approval clock" answered in one place rather than by walking a nested object, and a slot the design adds later becomes another row here instead of a change to this contract. - `tables` BoundTable[] - `role` string, required: The slot it fills: 'journal_lines', 'journal_headers', 'trial_balance', …. - `path` string, required: The uploaded file, e.g. 'ledger/journal.xlsx'. - `component` string, nullable: The tab, when the file contributed more than one table. - `table_name` string, required: The view name this run's SQL referenced it by. - `policy_sheets` string[]: Documents the run treated as settling parameters (a sequence policy, a topside register). - `columns` BoundColumn[]: Every column pinned to a slot, in slot order. - `slot` string, required: The slot this column fills, dotted: 'journal_key', 'clocks.created', 'amount_bases[reporting].debit', 'accounts.fsli'. - `path` string, required - `component` string, nullable - `table_name` string, required - `column` string, required - `detail` string, nullable: What the slot additionally states about this column — a clock's true grain, that a basis is the one the trial balance ties to, what a calendar date means. - `periods` BoundPeriod[]: The period domain, in period order, with roles. - `value` string, required - `role` string, required: 'opening', 'month', 'year_end_adj' or 'total_row'. - `value_sets` BoundValueSet[]: Encoding candidates and layer memberships. More than one entry under 'encodings.manual' means the run kept both readings and resolved them per test. - `slot` string, required: 'encodings.posted', 'encodings.manual', 'layers.book', …. - `name` string, required: The candidate's name, as a test spec cites it. - `path` string, required - `component` string, nullable - `table_name` string, required - `column` string, required - `values` string[]: The values of that column which mean this. - `note` string: Where this reading came from — a policy sheet, a flag column, a profiled domain. - `notes` string[]: Deviations the run observed while orienting. - `revised_because` string, nullable: Why the binding was replaced mid-run, when it was. Null on a run that bound once. - `tool_calls` ToolCallTrace[]: One entry per tool the run invoked, in execution order — the tool's name, a digest of its arguments, how many results came back, and how long it took. The run's shape, not its content. - `tool` string, required - `arguments_digest` string, required - `hits` integer, required - `duration_ms` integer, required - `steps_used` integer: Legacy procedure-step count retained for compatibility. It is engine-specific and is not a model-request count; agent runs expose completed root-model requests in `agent_usage`. Read it with `exhausted`, which says whether the configured request budget ran out before the run was satisfied. - `exhausted` boolean: Step budget hit before the run was satisfied. A successful response, not a failure. - `degraded` string, nullable: Why this result is degraded, when it is. The run broke before it could finalize an answer but had already computed real working, so what is published is that working — `sql_receipts` and `binding` — with `figures` empty and `answer` saying so. Null on every run that finished normally, exhausted ones included. - `quality` JetQuality: Structured execution-quality reporting for one JE-testing result. Distinguishes a clean, fully evidenced success from a recovered or partially validated one without changing ``ok`` or inventing figures. Contains only check names, tool names, outcome categories, and counts — never prompts, answers, evidence bodies, shell output, or client identifiers. - `status` 'clean' | 'recovered_with_warnings' | 'degraded', required: ``clean`` when nothing was recovered; ``recovered_with_warnings`` when a fail-open check, tool failure, or missing audit artifact was recorded; ``degraded`` when the run salvaged working after a hard failure (see ``JetResult.degraded``). - `validation_warnings` JetValidationWarning[]: Fail-open output checks that passed the answer through after their corrective retry. - `check` 'specs' | 'scope' | 'cycle' | 'grain' | 'basis' | 'absence' | 'bands' | 'pointer' | 'delivery' | 'figures', required: Stable machine-readable name of the fail-open check that was not satisfied. ``specs`` covers two causes: a finding that names no committed test, and a finding computed for a test the run still declared blocked by a missing parameter. - `status` 'failed_open': Always ``failed_open``: the check rejected the answer once, then passed it through. - `tool_failures` JetToolFailure[]: Non-success tool outcomes the agent recovered from, aggregated by tool and category. - `tool` string, required: Tool name that produced the non-success outcome (for example ``run_command``). - `outcome` 'model_retry' | 'command_error' | 'timeout' | 'tool_error', required: Category of the non-success: ``model_retry`` (a call the run corrected: a gate refusal, a rejected argument shape or a validation retry; does not lower `quality.status`), ``command_error`` (non-zero shell exit), ``timeout``, or ``tool_error`` (the tool itself failed, for example a SQL error). - `count` integer, required: How many times this tool×outcome pair occurred in the run. - `missing_artifacts` string[]: Required audit artifact classes absent from a quantitative result (``binding`` and/or ``sql_receipts``). Empty when every finding is ``cannot_be_performed`` or when both artifacts are present. - `retried_checks` string[]: Output-contract check families that cost the answer a model re-emission, whether or not the re-emission repaired them. Attribution only — a retry the model then satisfied is a clean answer, so this does not move ``status``. - `withheld_receipt_figures` integer: How many performed figures were published with no readable receipt id — either the statements behind them are not visible to this caller, or the figure was computed without one. The figures themselves are still returned; this counts the ones whose working cannot be inspected. - `execution_status` 'performed' | 'partially_performed' | 'not_performed', nullable: Whether the run tested what it was asked to test: ``performed`` when every figure was computed, ``partially_performed`` when some criteria could not be, ``not_performed`` when none could. Read it alongside `quality`, which grades how well a performed test went. JE-testing always sets this on a finished run; other JetResult subclasses (deep search) leave it null, as do results stored before the field existed. - `agent_usage` JetAgentUsage: Completed root-agent model requests by session phase. This is intentionally separate from :class:`SearchLlmUsage`: that ledger covers every nested LLM call and token, while this block explains the agent procedure itself. Provider transport attempts are not exposed by the model boundary reliably and are therefore not guessed here. - `execution_requests` integer, required: Completed model requests in normal execution cycles. - `compaction_requests` integer, required: Completed model requests used to summarize compacted history. - `finalization_requests` integer, required: Completed requests in the tool-less recovery finalizer. - `total_requests` integer, required: Sum of execution, compaction, and finalization requests. - `spec_digest` string, nullable: A short fingerprint of what this run committed to TEST — the rows, grain, clock, encoding, thresholds and time window each criterion was pinned to — with the free-text justifications beside those choices excluded. Two runs of the same question carry the same value when they tested the same thing, so an unstable answer can be told apart from an answer to a quietly different question without re-reading either run. Null on a run that committed no test spec, and on other JetResult subclasses. - `session_id` string, uuid, nullable: The conversation this run belongs to. Send it back as the request's `session_id` to ask a follow-up in the same thread. - `usage` SearchLlmUsage: What answering one search query cost in LLM work. Present only when the run was asked to account for itself *and* spend reached its ledger; ``null`` otherwise, so a caller can tell "nothing was measured" from "nothing was spent". An empty ledger publishes ``null`` rather than a zeroed object for that reason: zeros would claim a measured run cost nothing, when what an empty ledger most likely records is accounting that never landed. The totals cover recorded model calls at any depth: the agent's own turns, and the calls the retrieval tools made on its behalf — a document read by the recursive-LLM engine, a scan cracked by the vision engine, a tables question answered by the SQL agent. That is the number a per-query cost figure needs, and it is invariably several times the agent's own turn count. ``by_model`` is the same spend split by the model that served it, because a run legitimately spends on several at different prices — a total alone cannot be turned into money. The totals are the sum of ``by_model`` and are published anyway so the common case needs no arithmetic. Observed retries are included. These public token totals are not a complete cost certificate: provider omissions and failed persistence can leave gaps. Internal coverage and non-token counters stay in the ledger and are not added to this wire shape without a separate SDK contract update. - `requests` integer: Completed LLM requests, tool-internal ones included. - `input_tokens` integer: Prompt tokens across every request, cached ones included. - `output_tokens` integer: Completion tokens across every request. - `cached_input_tokens` integer: The share of input_tokens served from a provider prompt cache — billed at a reduced rate, so it is reported separately rather than subtracted. - `by_model` ModelTokenUsage[]: The same spend per model that served it, highest first. - `model` string, required: Model identifier as the provider reported it, or as the caller asked for it. - `requests` integer: Observed provider attempts, including explicitly recorded failures. - `input_tokens` integer: Prompt tokens sent to this model, cached ones included. - `output_tokens` integer: Completion tokens this model generated. - `cached_input_tokens` integer: The share of input_tokens served from the provider's prompt cache — billed at a reduced rate, so pricing needs it separated out rather than subtracted. - `grounding_job_ids` string[], nullable: Ground jobs planned for this search's evidences. Empty when postprocessing is disabled for this caller by deployment policy, explicitly disabled for the run, or no evidence is groundable. Absent on older results. When empty or absent, callers may POST /v1/ground explicitly to locate quotes. - `structured_answer` unknown - `command_receipts` CommandReceipt[]: Successful shell calculations cited by this answer. - `result_id` string, required: Job-scoped identity of a recorded shell execution. - `command` string, required: The shell command as executed. - `stdout` string, required: The complete standard output of the successful command. - `outputs` object, required: Named scalar outputs parsed from stdout; a scalar output is named value. - `claims` DeepSearchVerifiedClaim[]: Calculated answer values, each bound to the execution that produced it. - `claim_id` string, required: Unique id of this calculation within the result. - `answer_excerpt` string, nullable: Exact displayed answer value selected for its calculation citation. - `answer_occurrence` integer: Zero-based occurrence of answer_excerpt in the answer. - `evidence_indices` integer[]: Source evidence indices supporting the calculation inputs. - `claim` string, required: The method or formula behind the calculated value, as the agent wrote it. - `reference` DeepSearchClaimReference, required: A claim's address within a published SQL or command execution receipt. - `kind` 'result_cell' | 'result_count' | 'result_absence' | 'command_result', required: How the result supports the claim. - `result_id` string, required: The matching result_id in sql_receipts or command_receipts. - `row` integer, nullable: 0-based result row for a cell claim; null otherwise. - `column` string, nullable: Result column for a cell claim; null otherwise. - `cited_value` string, required: The exact value checked against the retained result. - `coverage` DeepSearchCoverage[]: Complete result tables the answer attached, each with server-rendered rows. - `deliverable_id` string, required: Unique id for one requested output. - `description` string, required: Requested output this item accounts for. - `basis` 'sql' | 'document' | 'calculation': Whether support is retained SQL or document retrieval; document absence is not a SQL-verified proof. - `evidence_indices` integer[]: Zero-based indices into this result's published evidences supporting a document deliverable. - `status` 'answered' | 'partial' | 'unanswerable', required: Whether the output was fully answerable. - `claim_ids` string[]: Verified claims satisfying this output. - `complete_result_id` string, nullable: Receipt containing the requested complete listing; page it when its attached breakdown is truncated. - `complete_result` JetBreakdown: The tabular result behind one figure, attached by the server. What a caller asking "by FSLI and month" or "top 10 preparers" wanted, in the shape the question implies. The rows are NOT model-authored and never were: they are the cited receipt's own result, stringified and capped here, attached at finalize from :class:`SqlReceipt` rows the run already published. That is the whole design — a figure's table costs the model no output tokens and cannot carry a cell no statement returned — and it is why there is no reshaping either: the receipt's shape IS the breakdown, so a matrix the SQL never grouped by month is a wrong statement rather than a rendering problem. ``result_id`` names the receipt the rows came from, which is always one of the figure's own citations — either on ``result_ids`` or its ``exception_listing_result_id``, the two id sets the console makes openable — so the breakdown is a convenience over the payload's own working, never a second source of truth, and a reader who wants the statement, the whole bounded result or its row provenance follows that id. (When the model names a listing it did not also list in ``receipt_ids``, that id reaches the figure through ``exception_listing_result_id`` rather than ``result_ids``; both render as receipt buttons, so the table stays one click away either way.) - `columns` string[]: Column names, in the statement's own result order. - `rows` array[]: Rows in receipt order, cells as text so a decimal, a date and a NULL all survive the wire. At most 200; a longer result sets `truncated` and stays whole on its receipt. - … - `truncated` boolean: Whether rows were cut — either by this table's own cap or already on the receipt it came from. A capped breakdown is never read as the complete listing. - `result_id` string, required: `sql_receipts[].result_id` of the statement these rows are. - `missing_inputs` string[]: Inputs preventing a complete answer. - `absence_result_ids` string[]: Zero-row receipts proving those inputs absent. - `cache` AnswerCacheInfo: How a search answer relates to the workspace's semantic answer cache. Present only on a run that served a previously derived answer instead of deriving a new one. Everything else on the result — the evidences, the reasoning, the tool-call trace, the receipts — describes that ORIGINAL derivation, which is what this block exists to say out loud: the answer was computed once, for a question near enough to this one, under an identical scope and an identical access gate, and re-checked against the workspace before it was handed back. A result with no ``cache`` block was derived by the run that returned it. - `served_from_cache` boolean, required: True when this result was re-served from a previously derived answer rather than computed by this run. Always true where this block appears at all. - `source_job_id` string, uuid, nullable: The job whose run originally derived this answer. Null when that job's row has since been reaped — the answer outlives the record of the run that produced it. - `cached_at` string, date-time, required: When the answer was originally derived. Read it as the age of the evidence: the workspace may have changed since, which is what the re-check below is for. - `verified_at` string, date-time, required: When this run re-checked the cached answer's citations against the workspace and accepted them. Always this run's own time — a cached answer is never served unchecked. - AutomaticAgentResult: The automatic search agent's answer, plus its published catalog selection when it made one. ``answer`` is a complete source-level deep-search result (citations, SQL receipts, confidence). ``catalog`` is present when the agent answered with a metadata-catalog query: the server re-executed it authoritatively, and its ``next_cursor`` pages through this job. - `result_type` 'automatic_agent': Identifies an automatic search agent result. - `answer` DeepSearchV2Result, required: The result of one source-level deep-search run (``JobKind.DEEP_SEARCH_V2``). Field-for-field the JET shape — answer, reasoning, evidences, the run's ``sql_receipts``, the tool-call trace, session handle, usage, exhaustion — under its own discriminator: the two kinds share one agent chassis and one fold, and a second field list here would only be a place for them to drift. On this surface a receipt's ``rows`` are the statement's bounded preview; the full result is retained server-side and re-queryable through the ``res_…`` handle appearing in any statement that pages it. - `result_type` 'deep_search_v2' - `answer` string, nullable: The direct, grounded answer to the request. Null only on a run that exhausted its budget before authoring one, or that asked `clarification_questions` instead. - `clarification` string, nullable: The run's clarifying questions as plain text, instead of an answer. Only ever set when the request carried `allow_clarification` and the run needed the user's input to go on; `answer` is null and `evidences` empty alongside it. The same questions, structured, are in `clarification_questions`. - `clarification_questions` ClarifyingQuestion[], nullable: The questions behind `clarification`, at most 2, each with up to 4 suggested answers. Answer them with a follow-up on `session_id` that repeats the query and carries `clarification_answers` (one entry per question, a null answer skips it), or with any follow-up query in your own words. Null on every run that answered. - `question` string, required: The question, as the run asked it. - `options` string[]: Suggested answers, most likely first. Never exhaustive: the user may always answer in their own words, so no option stands for 'Other'. Empty when the run offered none. - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - `population_statement` string, nullable: The population every figure was computed over — file, period, layer, status, basis, grain — in the run's own words. Null only on a run that never authored an answer. - `figures` JetFigure[]: One entry per criterion tested, each linked to the receipts its figures are readable out of. Empty on a run that answered without testing anything, or that exhausted its budget first. - `criterion` string, required: What was tested, in the caller's terms. - `definition` string, required: The definition it was tested under: which column and values encoded the term, which clock, which basis, which threshold and where it came from. - `spec_id` string, required: The run's committed TestSpec this figure was computed under. - `population` integer, required: The denominator — rows at this test's grain that the criterion ran over. - `count` integer, required: Members of the population that met the criterion. - `value` string, nullable: The exceptions' value as text, so a decimal survives the wire. Null for a count-only criterion. - `result_ids` string[]: `sql_receipts[].result_id` of every statement this figure is readable out of. - `exception_listing_result_id` string, nullable: The receipt that lists the exceptions themselves, when one was produced. - `band_group` string, nullable: Set when this figure is one band of a family that partitions a population — the same name on every band of the family, whose counts sum to that population. - `cannot_be_performed` boolean: The workspace does not hold the material this criterion needs. `result_ids` then name the probes that establish the absence rather than the figures. - `breakdown` JetBreakdown: The tabular result behind one figure, attached by the server. What a caller asking "by FSLI and month" or "top 10 preparers" wanted, in the shape the question implies. The rows are NOT model-authored and never were: they are the cited receipt's own result, stringified and capped here, attached at finalize from :class:`SqlReceipt` rows the run already published. That is the whole design — a figure's table costs the model no output tokens and cannot carry a cell no statement returned — and it is why there is no reshaping either: the receipt's shape IS the breakdown, so a matrix the SQL never grouped by month is a wrong statement rather than a rendering problem. ``result_id`` names the receipt the rows came from, which is always one of the figure's own citations — either on ``result_ids`` or its ``exception_listing_result_id``, the two id sets the console makes openable — so the breakdown is a convenience over the payload's own working, never a second source of truth, and a reader who wants the statement, the whole bounded result or its row provenance follows that id. (When the model names a listing it did not also list in ``receipt_ids``, that id reaches the figure through ``exception_listing_result_id`` rather than ``result_ids``; both render as receipt buttons, so the table stays one click away either way.) - … - `criteria` JetCriterionOutcome[]: Every requested test and its final disposition, including tests that never reached binding, measurement, or a published figure. Empty only on results stored before this checklist existed. - `criterion_id` string, required: Stable short id for this requested test. Its TestSpec and published figure use the same id. - `description` string, required: The requested test in the caller's terms, without an invented conclusion. - `status` 'performed' | 'cannot_be_performed' | 'incomplete', required: Whether the test produced a finding, proved it could not be performed, or remained incomplete. - `spec_id` string, nullable: The committed TestSpec id and matching `figures[].spec_id`. Null when setup never reached a spec. - `blocker` 'binding_unresolved' | 'measurement_failed' | 'missing_finding' | 'population_incomplete' | 'context_exhausted' | 'missing_business_parameter' | 'methodology_unresolved' | 'finding_unverified', nullable: Why an incomplete test did not finish, including reasons newer than the three `incomplete_reason` keeps to. Null for performed and cannot-be-performed tests. - `incomplete_reason` 'binding_unresolved' | 'measurement_failed' | 'missing_finding', nullable: `blocker` in the three values older SDKs accept: `population_incomplete` and `finding_unverified` read as `measurement_failed`, and every other newer blocker as `missing_finding`. Read `blocker` for the full reason. - `missing_parameters` string[]: Policy inputs this test was missing. Set only when `blocker` is `missing_business_parameter` or `methodology_unresolved`; empty otherwise. - `discrepancies` string[]: Where the data contradicted the request's premise or a figure it stated. Empty when nothing did — the run is asked for this explicitly, so an empty list is an answer rather than an omission. - `reasoning` string, nullable: How the receipted statements chain together into the answer. - `evidences` SearchEvidence[]: The material the answer cites, each resolved to the caller's own uploaded file. - `source_path` string, required: The uploaded file the quote belongs to, e.g. 'reports/policy.pdf'. This is the file to ground the quote against. - `source_file_id` string, uuid, nullable: The id of the file at source_path, resolved server-side. Always set on newly finalized results; null only on results stored before unresolvable citations were dropped. - `page` integer, nullable: 1-based page number, when the agent saw one. - `component` string, nullable: Public component of the file the quote came from — the tab name for a spreadsheet, the section for a split document; the same vocabulary file-metadata lists. Pass it as the ground target's sheet when grounding a spreadsheet quote. None for a single-component file or when attribution was unavailable. - `quote` string, required: The key passage, as retrieved from the file. - `passages` string[]: Contiguous pieces of the source file that quote was stitched from, in the file's own text. Ground each piece as its own target when this list is present, with max_matches 2. A piece that returns two matches repeats in the file, so which copy the quote used is unknown. A ' | ' marks a table cell boundary added by the check. Replace it with a space before grounding. Filled only for PDF, Word and PowerPoint sources that Ground reads from the PDF text layer. Absent when quote is already one contiguous passage, could not be checked, or could not be verified. - `relevance` string: Deprecated: empty on new results, where `reasoning` says how the evidences support the answer. - `queries` TableQueryGrounding[]: The SQL the run executed over this evidence's table, with a bounded preview of each result — server-recorded from the run's tables engine, never model-authored. Attached whenever the run queried the cited table (or the row extraction of the same spreadsheet tab), so a verbatim quote from a queried sheet carries the computation trail alongside it; empty when the run never queried the cited file's tables. - … - `derivation` DerivationTrace: The answer's computation DAG when evidence is derived rather than extracted. - … - `sql_receipts` SqlReceipt[]: Every statement the run executed, in execution order — the answer's working. - `result_id` string, required: Stable per-run identity of this statement, in execution order (e.g. 'sql_3'). - `sql` string, required: The statement as executed, verbatim. - `handle` string, nullable: Content-addressed key of this statement's stored result, derived from the statement text. Server-side identity: it is what lets the run's own publication find the stored result and its capture-time provenance, and it is NOT an address an agent may query or chain from — `result_id` is the identity the caller and the row pager use. Null on a run that stored no result for the statement. A `cat_` handle names an exploratory document-catalog query: it stores no result beyond the rows carried here. - `table_bindings` SqlTableBinding[]: The tables this statement registered, each with the view name it was referenced by. - … - `replay` SqlReplayReceipt: Immutable inputs and engine identity for independent result recomputation. - … - `columns` string[]: Result column names, in result order. - `rows` object[]: Result rows, values rendered as text so a decimal, a date and a NULL all survive the wire. - … - `row_count` integer: Rows carried below — not the statement's unbounded result size. - `result_row_count` integer: Rows in the statement's complete stored result. Equal to `row_count` when nothing was cut; the number a total or an exception count must be read from when `truncated` is set. - `truncated` boolean: Whether rows past the stored cap were cut from this receipt. - `grounding_status` 'exact' | 'unavailable' | 'zero_result', nullable: Whether this statement's stored result already carried proof of which source rows it read when the receipt was recorded. 'exact' means it did; 'unavailable' means the proof could not be read; 'zero_result' means there were no rows to ground. Null when nothing had been captured yet — the ordinary case for a lane that captures at publication time, so this is a record of what execution happened to know and NOT a prediction of whether the receipt can be grounded. What was actually proven is published as `grounding_status` on the matching evidence query, beside the `regions` it earned. - `views_used` string[]: Session views registered when this statement ran, in definition order — the registry snapshot it executed under. A statement naming a view is replayable only against these, which is what makes named views admissible where chaining a previous call's result handle is not. - `saved_as` string, nullable: The session view this statement was registered as, when it was. Every name in another receipt's ``views_used`` appears here on exactly one receipt, so the run's receipts define every view they cite. - `view_sql` string, nullable: The definition registered under `saved_as`, when it is not this statement itself. Null on an ordinary `save_as`, where `sql` IS the definition. Set by `build_journal_view`, which registers the per-journal frame and runs a bounded probe over it rather than materializing the whole frame — so the definition every later `views_used` refers to is still published by exactly one receipt. - `warnings` string[]: Pre-execution lint notes attached to this statement — non-blocking, and published as part of its working. - `executor` string, nullable: The named executor that generated this statement (`reconcile_movement`, `test_timing`, `find_duplicates`, `field_completeness`, `journal_balance`), when one did, `custom_sql` for a statement the fixed-pipeline engine authored under its escape, or `ledger_understanding` for the ledger-understanding census's own statement, which ran before this run and is cited rather than re-run. Null when no named generator produced it — a population count, an absence probe, or SQL the agent wrote itself. Both engines use the same words here. - `parameters` object: The executor's resolved call, flattened to text — the clock and its true grain, the window's day offsets, the signature, the tolerance, the population. Empty on a statement no executor generated. This is what makes a figure trace to a named, parameterized computation rather than to SQL alone. - `binding` LedgerBindingWire: The definitional layer a run committed, echoed for the caller to read. This is the answer to "on what definitions does this figure rest" — the question the prose relay of the old playbook could not answer, and the reason the binding is a validated artifact rather than a paragraph. Every pin was checked against the tables' own profiles before the run was allowed to compute anything: the columns exist with compatible types, the period roles partition the observed domain, each clock's declared grain matches its column, and every encoding value occurs in its column. Published as flat slot listings rather than as a mirror of the internal model's tree. Two reasons, both practical: a reader wants "which column is the approval clock" answered in one place rather than by walking a nested object, and a slot the design adds later becomes another row here instead of a change to this contract. - `tables` BoundTable[] - … - `policy_sheets` string[]: Documents the run treated as settling parameters (a sequence policy, a topside register). - `columns` BoundColumn[]: Every column pinned to a slot, in slot order. - … - `periods` BoundPeriod[]: The period domain, in period order, with roles. - … - `value_sets` BoundValueSet[]: Encoding candidates and layer memberships. More than one entry under 'encodings.manual' means the run kept both readings and resolved them per test. - … - `notes` string[]: Deviations the run observed while orienting. - `revised_because` string, nullable: Why the binding was replaced mid-run, when it was. Null on a run that bound once. - `tool_calls` ToolCallTrace[]: One entry per tool the run invoked, in execution order — the tool's name, a digest of its arguments, how many results came back, and how long it took. The run's shape, not its content. - `tool` string, required - `arguments_digest` string, required - `hits` integer, required - `duration_ms` integer, required - `steps_used` integer: Legacy procedure-step count retained for compatibility. It is engine-specific and is not a model-request count; agent runs expose completed root-model requests in `agent_usage`. Read it with `exhausted`, which says whether the configured request budget ran out before the run was satisfied. - `exhausted` boolean: Step budget hit before the run was satisfied. A successful response, not a failure. - `degraded` string, nullable: Why this result is degraded, when it is. The run broke before it could finalize an answer but had already computed real working, so what is published is that working — `sql_receipts` and `binding` — with `figures` empty and `answer` saying so. Null on every run that finished normally, exhausted ones included. - `quality` JetQuality: Structured execution-quality reporting for one JE-testing result. Distinguishes a clean, fully evidenced success from a recovered or partially validated one without changing ``ok`` or inventing figures. Contains only check names, tool names, outcome categories, and counts — never prompts, answers, evidence bodies, shell output, or client identifiers. - `status` 'clean' | 'recovered_with_warnings' | 'degraded', required: ``clean`` when nothing was recovered; ``recovered_with_warnings`` when a fail-open check, tool failure, or missing audit artifact was recorded; ``degraded`` when the run salvaged working after a hard failure (see ``JetResult.degraded``). - `validation_warnings` JetValidationWarning[]: Fail-open output checks that passed the answer through after their corrective retry. - … - `tool_failures` JetToolFailure[]: Non-success tool outcomes the agent recovered from, aggregated by tool and category. - … - `missing_artifacts` string[]: Required audit artifact classes absent from a quantitative result (``binding`` and/or ``sql_receipts``). Empty when every finding is ``cannot_be_performed`` or when both artifacts are present. - `retried_checks` string[]: Output-contract check families that cost the answer a model re-emission, whether or not the re-emission repaired them. Attribution only — a retry the model then satisfied is a clean answer, so this does not move ``status``. - `withheld_receipt_figures` integer: How many performed figures were published with no readable receipt id — either the statements behind them are not visible to this caller, or the figure was computed without one. The figures themselves are still returned; this counts the ones whose working cannot be inspected. - `execution_status` 'performed' | 'partially_performed' | 'not_performed', nullable: Whether the run tested what it was asked to test: ``performed`` when every figure was computed, ``partially_performed`` when some criteria could not be, ``not_performed`` when none could. Read it alongside `quality`, which grades how well a performed test went. JE-testing always sets this on a finished run; other JetResult subclasses (deep search) leave it null, as do results stored before the field existed. - `agent_usage` JetAgentUsage: Completed root-agent model requests by session phase. This is intentionally separate from :class:`SearchLlmUsage`: that ledger covers every nested LLM call and token, while this block explains the agent procedure itself. Provider transport attempts are not exposed by the model boundary reliably and are therefore not guessed here. - `execution_requests` integer, required: Completed model requests in normal execution cycles. - `compaction_requests` integer, required: Completed model requests used to summarize compacted history. - `finalization_requests` integer, required: Completed requests in the tool-less recovery finalizer. - `total_requests` integer, required: Sum of execution, compaction, and finalization requests. - `spec_digest` string, nullable: A short fingerprint of what this run committed to TEST — the rows, grain, clock, encoding, thresholds and time window each criterion was pinned to — with the free-text justifications beside those choices excluded. Two runs of the same question carry the same value when they tested the same thing, so an unstable answer can be told apart from an answer to a quietly different question without re-reading either run. Null on a run that committed no test spec, and on other JetResult subclasses. - `session_id` string, uuid, nullable: The conversation this run belongs to. Send it back as the request's `session_id` to ask a follow-up in the same thread. - `usage` SearchLlmUsage: What answering one search query cost in LLM work. Present only when the run was asked to account for itself *and* spend reached its ledger; ``null`` otherwise, so a caller can tell "nothing was measured" from "nothing was spent". An empty ledger publishes ``null`` rather than a zeroed object for that reason: zeros would claim a measured run cost nothing, when what an empty ledger most likely records is accounting that never landed. The totals cover recorded model calls at any depth: the agent's own turns, and the calls the retrieval tools made on its behalf — a document read by the recursive-LLM engine, a scan cracked by the vision engine, a tables question answered by the SQL agent. That is the number a per-query cost figure needs, and it is invariably several times the agent's own turn count. ``by_model`` is the same spend split by the model that served it, because a run legitimately spends on several at different prices — a total alone cannot be turned into money. The totals are the sum of ``by_model`` and are published anyway so the common case needs no arithmetic. Observed retries are included. These public token totals are not a complete cost certificate: provider omissions and failed persistence can leave gaps. Internal coverage and non-token counters stay in the ledger and are not added to this wire shape without a separate SDK contract update. - `requests` integer: Completed LLM requests, tool-internal ones included. - `input_tokens` integer: Prompt tokens across every request, cached ones included. - `output_tokens` integer: Completion tokens across every request. - `cached_input_tokens` integer: The share of input_tokens served from a provider prompt cache — billed at a reduced rate, so it is reported separately rather than subtracted. - `by_model` ModelTokenUsage[]: The same spend per model that served it, highest first. - … - `grounding_job_ids` string[], nullable: Ground jobs planned for this search's evidences. Empty when postprocessing is disabled for this caller by deployment policy, explicitly disabled for the run, or no evidence is groundable. Absent on older results. When empty or absent, callers may POST /v1/ground explicitly to locate quotes. - `structured_answer` unknown - `command_receipts` CommandReceipt[]: Successful shell calculations cited by this answer. - `result_id` string, required: Job-scoped identity of a recorded shell execution. - `command` string, required: The shell command as executed. - `stdout` string, required: The complete standard output of the successful command. - `outputs` object, required: Named scalar outputs parsed from stdout; a scalar output is named value. - `claims` DeepSearchVerifiedClaim[]: Calculated answer values, each bound to the execution that produced it. - `claim_id` string, required: Unique id of this calculation within the result. - `answer_excerpt` string, nullable: Exact displayed answer value selected for its calculation citation. - `answer_occurrence` integer: Zero-based occurrence of answer_excerpt in the answer. - `evidence_indices` integer[]: Source evidence indices supporting the calculation inputs. - `claim` string, required: The method or formula behind the calculated value, as the agent wrote it. - `reference` DeepSearchClaimReference, required: A claim's address within a published SQL or command execution receipt. - … - `coverage` DeepSearchCoverage[]: Complete result tables the answer attached, each with server-rendered rows. - `deliverable_id` string, required: Unique id for one requested output. - `description` string, required: Requested output this item accounts for. - `basis` 'sql' | 'document' | 'calculation': Whether support is retained SQL or document retrieval; document absence is not a SQL-verified proof. - `evidence_indices` integer[]: Zero-based indices into this result's published evidences supporting a document deliverable. - `status` 'answered' | 'partial' | 'unanswerable', required: Whether the output was fully answerable. - `claim_ids` string[]: Verified claims satisfying this output. - `complete_result_id` string, nullable: Receipt containing the requested complete listing; page it when its attached breakdown is truncated. - `complete_result` JetBreakdown: The tabular result behind one figure, attached by the server. What a caller asking "by FSLI and month" or "top 10 preparers" wanted, in the shape the question implies. The rows are NOT model-authored and never were: they are the cited receipt's own result, stringified and capped here, attached at finalize from :class:`SqlReceipt` rows the run already published. That is the whole design — a figure's table costs the model no output tokens and cannot carry a cell no statement returned — and it is why there is no reshaping either: the receipt's shape IS the breakdown, so a matrix the SQL never grouped by month is a wrong statement rather than a rendering problem. ``result_id`` names the receipt the rows came from, which is always one of the figure's own citations — either on ``result_ids`` or its ``exception_listing_result_id``, the two id sets the console makes openable — so the breakdown is a convenience over the payload's own working, never a second source of truth, and a reader who wants the statement, the whole bounded result or its row provenance follows that id. (When the model names a listing it did not also list in ``receipt_ids``, that id reaches the figure through ``exception_listing_result_id`` rather than ``result_ids``; both render as receipt buttons, so the table stays one click away either way.) - … - `missing_inputs` string[]: Inputs preventing a complete answer. - `absence_result_ids` string[]: Zero-row receipts proving those inputs absent. - `cache` AnswerCacheInfo: How a search answer relates to the workspace's semantic answer cache. Present only on a run that served a previously derived answer instead of deriving a new one. Everything else on the result — the evidences, the reasoning, the tool-call trace, the receipts — describes that ORIGINAL derivation, which is what this block exists to say out loud: the answer was computed once, for a question near enough to this one, under an identical scope and an identical access gate, and re-checked against the workspace before it was handed back. A result with no ``cache`` block was derived by the run that returned it. - `served_from_cache` boolean, required: True when this result was re-served from a previously derived answer rather than computed by this run. Always true where this block appears at all. - `source_job_id` string, uuid, nullable: The job whose run originally derived this answer. Null when that job's row has since been reaped — the answer outlives the record of the run that produced it. - `cached_at` string, date-time, required: When the answer was originally derived. Read it as the age of the evidence: the workspace may have changed since, which is what the re-check below is for. - `verified_at` string, date-time, required: When this run re-checked the cached answer's citations against the workspace and accepted them. Always this run's own time — a cached answer is never served unchecked. - `catalog` FilteredSearchResult: The typed outcome of one filtered-search execution (or one page of it). ``exhaustive`` is the coarse completeness signal: when it is false, returned matches are valid, but "all"-style claims, ``total_matches`` as a census, and zero-match conclusions are not guaranteed. It is scope-wide and all-or-nothing, so it cannot say *what* was incomplete; ``field_readability`` is its per-field companion, naming the filtered fields the extraction could not fully read — the difference between "no component matched" and "the column you filtered on was largely unreadable". Pagination is LIVE — each page re-executes against the current catalog, so concurrent ingestion, deletion, or relabeling may shift later pages (rows can repeat or be skipped across page boundaries); ``catalog_drifted`` says the scope changed since the query was first validated. - `result_type` 'filtered_search' - `result_unit` 'source' | 'component' | 'entity' | 'entry': The unit used for rows, totals, top-N and pagination. New searches consistently return catalog entries with their established identities. Legacy units remain readable. - `columns` CatalogColumnDescriptor[] - `field` string, required - `kind` 'text' | 'date' | 'money' | 'number' | 'boolean', required - `description` string - `repeated` boolean: Several values may exist per row (parties, signatories). - `filtered` boolean: The published query filtered on this column — or ranked by it under a top-N LIMIT, where ranking decides membership (server-extracted from the SQL, never model-authored). These are the values the matches hinge on, and the first cells worth grounding against their source documents. - `requested` boolean: The user requested this output field; missing values do not exclude a match. - `rows` FilteredSearchRow[] - `component` string, required: Public component name — the tab or document section, matching the component= argument of the file tools (qa-file, read-file, query-tables). Several document rows can share one section name; page_start/page_end distinguish them. A media row's name is the recording stem, display-only (file tools take the whole file). - `component_kind` 'document' | 'sheet' | 'media', required: The representation containing these observations. - `document_type` string, nullable: The profiled document type of this component. - `category` string, nullable: The component's primary taxonomy category. - `subcategory` string, nullable: The component's primary taxonomy subcategory. - `page_start` integer, nullable: First source page containing the component. - `page_end` integer, nullable: Last source page containing the component. - `summary` string: A description of the component's contents. - `entity_id` string, nullable: The printed identifier of the matching entity within a register. - `source_row` integer, nullable: The native sheet row containing this entity's facts. - `cells` FilteredSearchCell[]: Typed observations belonging to this component. - … - `content_matches` ContentConditionMatch[]: Content criteria this row satisfied, with observed values and the source passages used to verify them. - … - `source_path` string, required: The uploaded file the result belongs to. - `source_file_id` string, uuid, required: Stable identity of the uploaded source file. - `entry_id` string, uuid, nullable: Catalog entry identity, independent of query wording, filtering and rank. Supporting profile records share an established structural identity; incomplete identities can change on catalog rebuild. Null on legacy units. - `components` FilteredSearchComponent[]: Supporting records grouped into this result, in query order, with their separate values and evidence. The row's component fields mirror the first record for display. Empty when no grouping was needed or on older results. - … - `content_verification` ContentVerificationSummary: Coverage of the bounded content check, separate from catalog coverage. - `condition` string, required: The content condition checked on catalog-selected candidates. - `candidates` integer, required: Catalog candidates considered by the cited content check. - `unverified_candidates` integer, required: Candidates whose condition could neither be established nor ruled out, including bounds or unavailable evidence. These records are excluded from confirmed matches, not treated as non-matches. - `total_matches` integer: Confirmed matches in result_unit, before any page or top-N cut. - `total_files` integer, nullable: Distinct source files supporting the confirmed matches before any page or top-N cut. Null for older results or when no authoritative selection was executed. Subject to the same completeness as total_matches. - `next_cursor` string, nullable: Opaque cursor for the next page — POST it back as {type: 'page', cursor}. Null on the last page. - `exhaustive` boolean: True only when every eligible component was completely cataloged and evaluated — the scope-wide completeness signal. False whenever coverage is partial or a residual content condition was applied. - `truncated` boolean: A structural cap degraded this result; matches shown remain valid. - `executed_at` string, date-time, nullable: When this page's snapshot was read. - `catalog_drifted` boolean: The catalog changed since the query was validated. - `applied_query` string, nullable: Server-rendered display form of the published query. - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - `clarification` string, nullable: Non-null exactly when the run asked a clarifying question instead of executing — only possible when the initial query set `allow_clarification`: no rows, no applied_query, exhaustive false. Filtered search keeps no session; answer it by issuing a new initial query. - `content_evidences` ContentEvidence[]: Residual content condition passages, server-verified; present only on residual queries. - `source_path` string, required - `source_file_id` string, uuid, required - `component` string, nullable - `page` integer, nullable - `a1_range` string, nullable: The exact native cell or range containing this quotation, within component. - `quote` string, required - `evidences` SearchEvidence[]: Referent-resolution evidence: the file passages that turned a role or relative referent in the query ('the CEO') into the concrete filter value the published query uses. Agent-cited, then resolved server-side to the caller's own uploaded file exactly like search evidence — an entry that cannot be resolved to a visible file is dropped, never published. Distinct from content_evidences, which are server-verified residual matches. Empty on pure catalog queries. - `source_path` string, required: The uploaded file the quote belongs to, e.g. 'reports/policy.pdf'. This is the file to ground the quote against. - `source_file_id` string, uuid, nullable: The id of the file at source_path, resolved server-side. Always set on newly finalized results; null only on results stored before unresolvable citations were dropped. - `page` integer, nullable: 1-based page number, when the agent saw one. - `component` string, nullable: Public component of the file the quote came from — the tab name for a spreadsheet, the section for a split document; the same vocabulary file-metadata lists. Pass it as the ground target's sheet when grounding a spreadsheet quote. None for a single-component file or when attribution was unavailable. - `quote` string, required: The key passage, as retrieved from the file. - `passages` string[]: Contiguous pieces of the source file that quote was stitched from, in the file's own text. Ground each piece as its own target when this list is present, with max_matches 2. A piece that returns two matches repeats in the file, so which copy the quote used is unknown. A ' | ' marks a table cell boundary added by the check. Replace it with a space before grounding. Filled only for PDF, Word and PowerPoint sources that Ground reads from the PDF text layer. Absent when quote is already one contiguous passage, could not be checked, or could not be verified. - `relevance` string: Deprecated: empty on new results, where `reasoning` says how the evidences support the answer. - `queries` TableQueryGrounding[]: The SQL the run executed over this evidence's table, with a bounded preview of each result — server-recorded from the run's tables engine, never model-authored. Attached whenever the run queried the cited table (or the row extraction of the same spreadsheet tab), so a verbatim quote from a queried sheet carries the computation trail alongside it; empty when the run never queried the cited file's tables. - … - `derivation` DerivationTrace: The answer's computation DAG when evidence is derived rather than extracted. - … - `field_readability` FieldReadability[]: Filtered fields the extraction could not fully read, server-computed. An empty list is an answer — every field the query filtered on was fully readable — rather than an omission. - `field` string, required: The extracted field the query filtered on. - `in_scope` integer, required: Components in scope whose document type carries this field. - `readable` integer, required: Of those, how many had a resolved value the predicate could evaluate. - `coverage` Coverage: What the access gate withheld, in counts and label names only. Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request. - `restricted_candidates` integer - `labels_required` string[]: Which labels would have been needed to see the withheld candidates. - `request_access_hint` string, nullable - `tool_calls` ToolCallTrace[] - `tool` string, required - `arguments_digest` string, required - `hits` integer, required - `duration_ms` integer, required - `steps_used` integer - `exhausted` boolean: Step budget hit before the agent finished. A success, not a failure. - `candidates_seen` integer - AutomaticSearchResult - `result_type` 'automatic_search': Identifies an automatic search result. - `output` union, required: The selected pipeline's native result, preserving citations, completeness, and pagination. - IntelligentSearchResult - `result_type` 'intelligent_search' - `claims` DeepSearchVerifiedClaim[]: Calculated answer values bound to recorded executions. - … - `command_receipts` CommandReceipt[]: Successful shell calculations cited by this answer. - … - `sql_receipts` SqlReceipt[]: SQL executions supporting calculated answer claims. - … - `evidences` SearchEvidence[]: The evidence the agent found for the query, in order of importance. - … - `reasoning` string, nullable: The agent's account of how the pieces of evidence chain together to address the query, including any assumption it made in reading the query. - `answer` string, nullable: A direct answer to the query, grounded in the evidences. Always present on a newly finalized run that answered; null when the run rejected the query with a `clarification`, and on results stored before answers became unconditional (the evidence-only mode). - `structured_answer` unknown - `clarification` string, nullable: Non-null exactly when the run rejected the query as genuinely ambiguous instead of answering — only possible when the request set `allow_clarification`: one direct question back to the caller, with `answer` and `reasoning` null and `evidences` empty. Answer it by re-asking in the same thread via the result's `session_id`. - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - `coverage` Coverage: What the access gate withheld, in counts and label names only. Never a name, path, or fragment of withheld content. Naming the labels leaks nothing the caller cannot already read from the workspace config, and it turns "some results were withheld" into an actionable request. - … - `candidates_seen` integer - `steps_used` integer - `exhausted` boolean: Budget hit before the loop was satisfied. A successful response, not a failure. When the agent authored no answer or reasoning, reasoning carries an actionable briefing and answer stays null so presentation does not treat the briefing as an answer. - `tool_calls` ToolCallTrace[] - … - `session_id` string, uuid, nullable: The conversation this run belongs to. Send it back as the request's `session_id` to ask a follow-up in the same thread. Null only on results finalized before sessions existed. - `cache` AnswerCacheInfo: How a search answer relates to the workspace's semantic answer cache. Present only on a run that served a previously derived answer instead of deriving a new one. Everything else on the result — the evidences, the reasoning, the tool-call trace, the receipts — describes that ORIGINAL derivation, which is what this block exists to say out loud: the answer was computed once, for a question near enough to this one, under an identical scope and an identical access gate, and re-checked against the workspace before it was handed back. A result with no ``cache`` block was derived by the run that returned it. - … - `usage` SearchLlmUsage: What answering one search query cost in LLM work. Present only when the run was asked to account for itself *and* spend reached its ledger; ``null`` otherwise, so a caller can tell "nothing was measured" from "nothing was spent". An empty ledger publishes ``null`` rather than a zeroed object for that reason: zeros would claim a measured run cost nothing, when what an empty ledger most likely records is accounting that never landed. The totals cover recorded model calls at any depth: the agent's own turns, and the calls the retrieval tools made on its behalf — a document read by the recursive-LLM engine, a scan cracked by the vision engine, a tables question answered by the SQL agent. That is the number a per-query cost figure needs, and it is invariably several times the agent's own turn count. ``by_model`` is the same spend split by the model that served it, because a run legitimately spends on several at different prices — a total alone cannot be turned into money. The totals are the sum of ``by_model`` and are published anyway so the common case needs no arithmetic. Observed retries are included. These public token totals are not a complete cost certificate: provider omissions and failed persistence can leave gaps. Internal coverage and non-token counters stay in the ledger and are not added to this wire shape without a separate SDK contract update. - … - `grounding_job_ids` string[], nullable: Ground jobs planned for this search's evidences. Empty when postprocessing is disabled for this caller by deployment policy, explicitly disabled for the run, or no evidence is groundable. Absent on older results. When empty or absent, callers may POST /v1/ground explicitly to locate quotes. - AutomaticAgentResult: The automatic search agent's answer, plus its published catalog selection when it made one. ``answer`` is a complete source-level deep-search result (citations, SQL receipts, confidence). ``catalog`` is present when the agent answered with a metadata-catalog query: the server re-executed it authoritatively, and its ``next_cursor`` pages through this job. - `result_type` 'automatic_agent': Identifies an automatic search agent result. - `answer` DeepSearchV2Result, required: The result of one source-level deep-search run (``JobKind.DEEP_SEARCH_V2``). Field-for-field the JET shape — answer, reasoning, evidences, the run's ``sql_receipts``, the tool-call trace, session handle, usage, exhaustion — under its own discriminator: the two kinds share one agent chassis and one fold, and a second field list here would only be a place for them to drift. On this surface a receipt's ``rows`` are the statement's bounded preview; the full result is retained server-side and re-queryable through the ``res_…`` handle appearing in any statement that pages it. - … - `catalog` FilteredSearchResult: The typed outcome of one filtered-search execution (or one page of it). ``exhaustive`` is the coarse completeness signal: when it is false, returned matches are valid, but "all"-style claims, ``total_matches`` as a census, and zero-match conclusions are not guaranteed. It is scope-wide and all-or-nothing, so it cannot say *what* was incomplete; ``field_readability`` is its per-field companion, naming the filtered fields the extraction could not fully read — the difference between "no component matched" and "the column you filtered on was largely unreadable". Pagination is LIVE — each page re-executes against the current catalog, so concurrent ingestion, deletion, or relabeling may shift later pages (rows can repeat or be skipped across page boundaries); ``catalog_drifted`` says the scope changed since the query was first validated. - … - DeepSearchV2Result: The result of one source-level deep-search run (``JobKind.DEEP_SEARCH_V2``). Field-for-field the JET shape — answer, reasoning, evidences, the run's ``sql_receipts``, the tool-call trace, session handle, usage, exhaustion — under its own discriminator: the two kinds share one agent chassis and one fold, and a second field list here would only be a place for them to drift. On this surface a receipt's ``rows`` are the statement's bounded preview; the full result is retained server-side and re-queryable through the ``res_…`` handle appearing in any statement that pages it. - `result_type` 'deep_search_v2' - `answer` string, nullable: The direct, grounded answer to the request. Null only on a run that exhausted its budget before authoring one, or that asked `clarification_questions` instead. - `clarification` string, nullable: The run's clarifying questions as plain text, instead of an answer. Only ever set when the request carried `allow_clarification` and the run needed the user's input to go on; `answer` is null and `evidences` empty alongside it. The same questions, structured, are in `clarification_questions`. - `clarification_questions` ClarifyingQuestion[], nullable: The questions behind `clarification`, at most 2, each with up to 4 suggested answers. Answer them with a follow-up on `session_id` that repeats the query and carries `clarification_answers` (one entry per question, a null answer skips it), or with any follow-up query in your own words. Null on every run that answered. - … - `confidence` 'certain' | 'very_high' | 'high' | 'medium' | 'low' | 'speculative': How well the retrieved evidence supports the answer, worst-case wins. - `population_statement` string, nullable: The population every figure was computed over — file, period, layer, status, basis, grain — in the run's own words. Null only on a run that never authored an answer. - `figures` JetFigure[]: One entry per criterion tested, each linked to the receipts its figures are readable out of. Empty on a run that answered without testing anything, or that exhausted its budget first. - … - `criteria` JetCriterionOutcome[]: Every requested test and its final disposition, including tests that never reached binding, measurement, or a published figure. Empty only on results stored before this checklist existed. - … - `discrepancies` string[]: Where the data contradicted the request's premise or a figure it stated. Empty when nothing did — the run is asked for this explicitly, so an empty list is an answer rather than an omission. - `reasoning` string, nullable: How the receipted statements chain together into the answer. - `evidences` SearchEvidence[]: The material the answer cites, each resolved to the caller's own uploaded file. - … - `sql_receipts` SqlReceipt[]: Every statement the run executed, in execution order — the answer's working. - … - `binding` LedgerBindingWire: The definitional layer a run committed, echoed for the caller to read. This is the answer to "on what definitions does this figure rest" — the question the prose relay of the old playbook could not answer, and the reason the binding is a validated artifact rather than a paragraph. Every pin was checked against the tables' own profiles before the run was allowed to compute anything: the columns exist with compatible types, the period roles partition the observed domain, each clock's declared grain matches its column, and every encoding value occurs in its column. Published as flat slot listings rather than as a mirror of the internal model's tree. Two reasons, both practical: a reader wants "which column is the approval clock" answered in one place rather than by walking a nested object, and a slot the design adds later becomes another row here instead of a change to this contract. - … - `tool_calls` ToolCallTrace[]: One entry per tool the run invoked, in execution order — the tool's name, a digest of its arguments, how many results came back, and how long it took. The run's shape, not its content. - … - `steps_used` integer: Legacy procedure-step count retained for compatibility. It is engine-specific and is not a model-request count; agent runs expose completed root-model requests in `agent_usage`. Read it with `exhausted`, which says whether the configured request budget ran out before the run was satisfied. - `exhausted` boolean: Step budget hit before the run was satisfied. A successful response, not a failure. - `degraded` string, nullable: Why this result is degraded, when it is. The run broke before it could finalize an answer but had already computed real working, so what is published is that working — `sql_receipts` and `binding` — with `figures` empty and `answer` saying so. Null on every run that finished normally, exhausted ones included. - … truncated; see the full OpenAPI document linked below ## Other responses - `202`: Durable table QA accepted; poll the Location URL. - `400`: Bad Request - `401`: Unauthorized - `402`: Payment Required - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `410`: Gone - `413`: Request Entity Too Large - `422`: Unprocessable Entity - `424`: Failed Dependency - `429`: Too Many Requests - `500`: Internal Server Error - `501`: Not Implemented - `503`: Service Unavailable - `504`: Gateway Timeout --- [API](https://skmtc.dev/nace/apis/ndi-service.md) - [All operations](https://skmtc.dev/nace/apis/ndi-service/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/ndi-service/revisions/d9d1f8ec2207?raw)