--- title: "get_job_request" method: GET path: "/v1/jobs/{job_id}/request" tags: ["operations"] --- # get_job_request `GET /v1/jobs/{job_id}/request` ## Request - Base URL: `https://ndi-api.nace.ai` - URL: `https://ndi-api.nace.ai/v1/jobs/{job_id}/request` - Auth: API key in header `X-API-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Read back the request a document operation ran under. Cost class: fast. What a finished run was *asked* for — the page selection, the schema, the targets — so a caller can show the settings that produced a result, rebuild the call that made it, or submit it again. ``Job.source`` names the document; this names everything else. Its own route rather than a field on ``Job``: an extract schema or a ground target list is large, and ``GET /v1/jobs`` returns up to 200 rows. Retention is the same as the result's — the request is read from the stored payload, so it dies with it rather than outliving it. ## Path parameters - `job_id` string, uuid, required: Job identifier. ## Response `200` Successful Response - union - ParseRequestEcho - SplitRequestEcho: A stored ``split`` request, read back. - `classes` SplitCategory[], required: Document classes to split the packet into; spreadsheets classify worksheets against these classes. - `description` string - `id` string, required - `instance_key` SplitInstanceKey - `description` string, required - `name` string, required - `required` boolean - `label` string, required - `subclasses` SplitSubclass[] - `description` string - `id` string, required - `label` string, required - `corpus_sources` WorkspaceFileSource[]: Workspace files visible in the run tray, including files not submitted by this request. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - `name` string, nullable: Optional display name. Public Parse, Split, Classify, Extract, and Ground runs use a stable server default when blank. The console calls a named run a 'project'. - `output` SplitOutputOptions - `include_content` boolean: When true, each segment includes its extracted markdown in content. - `materialize_files` boolean: When true, each document segment includes a downloadable artifact URL. Spreadsheet segments always include a single-sheet XLSX URL, even when this is false. - `output_workspace_id` string, uuid, nullable: Workspace for retained result artifacts. Defaults to the unique source workspace, or a reused Parse's output workspace. Required for ambiguous destinations involving customer storage. Does not change source access. - `overlap_policy` 'exclusive' | 'shared_boundary_page': Whether a boundary page may belong to two adjacent segments or only one. - `page_ranges` PageRange[], nullable: One-based inclusive page ranges to consider. Omit to use the whole document. - `end` integer, required: Last page of the range, 1-based and inclusive. - `start` integer, required: First page of the range, 1-based and inclusive. - `parse` ParseSettings: Settings for the Parse that runs before Split, Classify, or Extract. A subset of the ``POST /v1/parse`` body with the same field names and nested models. Options that only shape the Parse response (``output``, ``chunking``) and options the runtime refuses (``quality``, ``ocr``) are not accepted here. A setting the file type cannot use is accepted and reported in the result's warnings. - `diagrams` ParseDiagramsOptions - `mode` 'omit' | 'mermaid': Whether flowchart-like figures stay as images or are rewritten as Mermaid fences. - `figures` ParseSettingsFigures: How figure regions are kept in the Parse behind an operation. - `mode` 'omit' | 'include' | 'describe', required: omit drops figure regions from the Parse this operation reads. include and describe both keep them and are the default: the operation reads the same Parse for either. - `page_ranges` PageRange[], nullable: One-based inclusive pages to read, as page_ranges on Parse. On an operation with its own page_ranges the two must agree. With a parse_result source it keeps only those pages of the reused Parse. - `end` integer, required: Last page of the range, 1-based and inclusive. - `start` integer, required: First page of the range, 1-based and inclusive. - `parse_mode` 'high' | 'medium' | 'low', nullable: Parsing effort for the Parse before this operation, as parse_mode on Parse. Omit to use the request's top-level parse_mode, which defaults to low. - `spreadsheet` ParseSpreadsheetOptions: Workbook-specific Parse controls for spreadsheet sources. Defaults preserve the pre-control behavior: every sheet/row/column is included and formula *source text* is omitted (cached values still appear). - `include_formulas` boolean: When true, include formula source text. Cached calculated values are always present. - `include_hidden_columns` boolean: When false, skip columns marked hidden. - `include_hidden_rows` boolean: When false, skip rows marked hidden. - `include_hidden_sheets` boolean: When false, skip sheets marked hidden in the workbook. - `sheets` string[], nullable: Optional sheet-name filter. When set, only listed sheets are parsed, in workbook order. - `parse_mode` 'low' | 'medium' | 'high': How much parsing effort to use: Low uses native OCR, Medium routes to the best parser, and High adds page verification and correction. - `project_id` string, uuid, nullable: Caller-minted grouping id; jobs submitted together share it. Not a server-side resource. - `quality` 'auto' | 'fast' | 'accurate': Latency versus accuracy preference for this run. Only auto is accepted today. - `request_type` 'split' - `source` union, required: The packet to split: a fresh upload, an HTTPS URL, a workspace file, or a prior parse job. - 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. - `file_name` string, required: Filename to record for the fetched bytes. - `type` 'url' - `url` string, required: HTTPS URL the service fetches. - 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. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - ParseResultSource: A prior Parse job whose parsed artifact can be reused by downstream methods. - `job_id` string, uuid, required: Succeeded parse job whose artifact should be reused. - `type` 'parse_result' - `split_rules` string, nullable: Optional free-text guidance for how to cut the packet (for example, split on cover sheets). - `unknown_policy` 'include' | 'force' | 'error': What to do with pages that match no class. include keeps them as unclassified; force assigns the best class; error fails the job. - ClassifyRequestEcho: A stored ``classify`` request, read back. - `classes` ClassifyClass[], required: Caller-defined classes to score the document against. - `criteria` string[]: Optional extra rules the model should apply when scoring this class. - `description` string: What belongs in this class. Used as model guidance. - `id` string, required: Stable caller-defined id returned on labels. Not the reserved other group. - `label` string, required: Human-readable class name shown in results. - `subclasses` ClassifySubclass[]: Optional finer labels nested under this class. - `criteria` string[] - `description` string - `id` string, required - `label` string, required - `context` ClassifyContext: Caller-supplied context about the document being classified. Today this carries only the audited entity's name. Direction-sensitive categories (``supplier_invoice`` vs ``sales_invoice``, ``customer_purchase_order`` vs ``purchase_order``, and similar pairs across the taxonomy) read the same document two different ways depending on which side of it is the audited entity, and the model is never told that otherwise. Naming it here lets the decision read the document's own buyer/supplier or issuer/recipient cues against the right side. - `entity_aliases` string[]: Other names the audited entity is known by in its documents (trading names, former names, abbreviations). - `entity_name` string, nullable: The audited entity's name, exactly as it would appear on its own letterhead or as the counterparty on a document it did not issue. Omit when the caller does not know it or it does not apply; direction-sensitive categories are then decided without the hint, as they always have been. - `corpus_sources` WorkspaceFileSource[]: Workspace files visible in the run tray, including files not submitted by this request. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - `granularity` 'document' | 'page': Score the whole document once, or return one unit per selected page. - `name` string, nullable: Optional display name. Public Parse, Split, Classify, Extract, and Ground runs use a stable server default when blank. The console calls a named run a 'project'. - `output` ClassifyOutputOptions - `delivery` 'progressive' | 'complete': Progressive publishes labels on the running job before the reason finishes. Complete waits for reasons (or their failure) before any result. Only meaningful when include_reason is true. Does not change the final result. - `include_reason` boolean: When true, each label may include a short reason string. - `max_alternatives` integer: How many ranked labels to return per unit, including the winner. - `output_workspace_id` string, uuid, nullable: Workspace for retained result artifacts. Defaults to the unique source workspace, or a reused Parse's output workspace. Required for ambiguous destinations involving customer storage. Does not change source access. - `page_ranges` PageRange[], nullable: One-based inclusive page ranges to classify. Omit to use the whole document. Not supported for spreadsheets (.xlsx, .xls, .xlsm, .csv, .parquet): the request is refused with 422 invalid_request and detail.reason spreadsheet_source. A workspace file is a spreadsheet when file_type on GET /v1/workspaces/{workspace_id}/files/{file_id} is one of those extensions. - `end` integer, required: Last page of the range, 1-based and inclusive. - `start` integer, required: First page of the range, 1-based and inclusive. - `parse` ParseSettings: Settings for the Parse that runs before Split, Classify, or Extract. A subset of the ``POST /v1/parse`` body with the same field names and nested models. Options that only shape the Parse response (``output``, ``chunking``) and options the runtime refuses (``quality``, ``ocr``) are not accepted here. A setting the file type cannot use is accepted and reported in the result's warnings. - `diagrams` ParseDiagramsOptions - `mode` 'omit' | 'mermaid': Whether flowchart-like figures stay as images or are rewritten as Mermaid fences. - `figures` ParseSettingsFigures: How figure regions are kept in the Parse behind an operation. - `mode` 'omit' | 'include' | 'describe', required: omit drops figure regions from the Parse this operation reads. include and describe both keep them and are the default: the operation reads the same Parse for either. - `page_ranges` PageRange[], nullable: One-based inclusive pages to read, as page_ranges on Parse. On an operation with its own page_ranges the two must agree. With a parse_result source it keeps only those pages of the reused Parse. - `end` integer, required: Last page of the range, 1-based and inclusive. - `start` integer, required: First page of the range, 1-based and inclusive. - `parse_mode` 'high' | 'medium' | 'low', nullable: Parsing effort for the Parse before this operation, as parse_mode on Parse. Omit to use the request's top-level parse_mode, which defaults to low. - `spreadsheet` ParseSpreadsheetOptions: Workbook-specific Parse controls for spreadsheet sources. Defaults preserve the pre-control behavior: every sheet/row/column is included and formula *source text* is omitted (cached values still appear). - `include_formulas` boolean: When true, include formula source text. Cached calculated values are always present. - `include_hidden_columns` boolean: When false, skip columns marked hidden. - `include_hidden_rows` boolean: When false, skip rows marked hidden. - `include_hidden_sheets` boolean: When false, skip sheets marked hidden in the workbook. - `sheets` string[], nullable: Optional sheet-name filter. When set, only listed sheets are parsed, in workbook order. - `parse_mode` 'low' | 'medium' | 'high': How much parsing effort to use: Low uses native OCR, Medium routes to the best parser, and High adds page verification and correction. - `project_id` string, uuid, nullable: Caller-minted grouping id; jobs submitted together share it. Not a server-side resource. - `request_type` 'classify' - `source` union, required: The document to classify. A parse_result reuses the stored text of a succeeded Parse job. - 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. - `file_name` string, required: Filename to record for the fetched bytes. - `type` 'url' - `url` string, required: HTTPS URL the service fetches. - 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. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - ParseResultSource: A prior Parse job whose parsed artifact can be reused by downstream methods. - `job_id` string, uuid, required: Succeeded parse job whose artifact should be reused. - `type` 'parse_result' - `unknown_policy` 'allow' | 'force_best': allow may mark a unit unknown. force_best commits an ambiguous unit to one of your classes instead of abstaining. A blank or unreadable page the model sees is assigned the closest listed class — the closed decode vocabulary has no page-state tokens. A unit that could not be parsed is still returned unknown, and so is an empty spreadsheet tab. Pages never read by any model because of document size are also returned unknown and disclosed as classification_unread_pages. - CategorizeRequestEcho: A stored ``categorize`` request, read back. - `allow_unknown` boolean: When true, the model may assign none of the above if nothing fits confidently. - `corpus_sources` WorkspaceFileSource[]: Workspace files visible in the run tray, including files not submitted by this request. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - `domain_id` string, nullable: Registered domain vocabulary to classify against when taxonomy is omitted. - `name` string, nullable: Optional display name. Public Parse, Split, Classify, Extract, and Ground runs use a stable server default when blank. The console calls a named run a 'project'. - `output_workspace_id` string, uuid, nullable: Workspace for retained result artifacts. Defaults to the unique source workspace, or a reused Parse's output workspace. Required for ambiguous destinations involving customer storage. Does not change source access. - `parse` ParseSettings: Settings for the Parse that runs before Split, Classify, or Extract. A subset of the ``POST /v1/parse`` body with the same field names and nested models. Options that only shape the Parse response (``output``, ``chunking``) and options the runtime refuses (``quality``, ``ocr``) are not accepted here. A setting the file type cannot use is accepted and reported in the result's warnings. - `diagrams` ParseDiagramsOptions - `mode` 'omit' | 'mermaid': Whether flowchart-like figures stay as images or are rewritten as Mermaid fences. - `figures` ParseSettingsFigures: How figure regions are kept in the Parse behind an operation. - `mode` 'omit' | 'include' | 'describe', required: omit drops figure regions from the Parse this operation reads. include and describe both keep them and are the default: the operation reads the same Parse for either. - `page_ranges` PageRange[], nullable: One-based inclusive pages to read, as page_ranges on Parse. On an operation with its own page_ranges the two must agree. With a parse_result source it keeps only those pages of the reused Parse. - `end` integer, required: Last page of the range, 1-based and inclusive. - `start` integer, required: First page of the range, 1-based and inclusive. - `parse_mode` 'high' | 'medium' | 'low', nullable: Parsing effort for the Parse before this operation, as parse_mode on Parse. Omit to use the request's top-level parse_mode, which defaults to low. - `spreadsheet` ParseSpreadsheetOptions: Workbook-specific Parse controls for spreadsheet sources. Defaults preserve the pre-control behavior: every sheet/row/column is included and formula *source text* is omitted (cached values still appear). - `include_formulas` boolean: When true, include formula source text. Cached calculated values are always present. - `include_hidden_columns` boolean: When false, skip columns marked hidden. - `include_hidden_rows` boolean: When false, skip rows marked hidden. - `include_hidden_sheets` boolean: When false, skip sheets marked hidden in the workbook. - `sheets` string[], nullable: Optional sheet-name filter. When set, only listed sheets are parsed, in workbook order. - `parse_mode` 'low' | 'medium' | 'high': How much parsing effort to use: Low uses native OCR, Medium routes to the best parser, and High adds page verification and correction. - `project_id` string, uuid, nullable: Caller-minted grouping id; jobs submitted together share it. Not a server-side resource. - `request_type` 'categorize' - `source` union: Single document to classify. Exactly one of source or sources must be set. - 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. - `file_name` string, required: Filename to record for the fetched bytes. - `type` 'url' - `url` string, required: HTTPS URL the service fetches. - 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. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - ParseResultSource: A prior Parse job whose parsed artifact can be reused by downstream methods. - `job_id` string, uuid, required: Succeeded parse job whose artifact should be reused. - `type` 'parse_result' - `sources` union[], nullable: Batch of documents to classify. Exactly one of source or sources must be set. - union - 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. - `file_name` string, required: Filename to record for the fetched bytes. - `type` 'url' - `url` string, required: HTTPS URL the service fetches. - 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. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - ParseResultSource: A prior Parse job whose parsed artifact can be reused by downstream methods. - `job_id` string, uuid, required: Succeeded parse job whose artifact should be reused. - `type` 'parse_result' - `taxonomy` CategorizeTaxonomy - `allow_freeform` boolean - `categories` CategorizeTaxonomyCategory[], required - `description` string, nullable - `key` string, required - `subcategories` CategorizeTaxonomySubcategory[], required - `description` string, nullable - `key` string, required - `vocabulary` string[], nullable: Legacy flat category list. Prefer taxonomy or a registered domain_id. - ExtractRequestEcho - GroundRequestEcho: A stored ``ground`` request, read back. - `claims` Claim[], nullable: Legacy locator shape. Prefer targets. Exactly one of claims or targets must be set. - `claim_id` string, required - `hint` string, nullable - `text` string, required - `corpus_sources` WorkspaceFileSource[]: Workspace files visible in the run tray, including files not submitted by this request. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - `name` string, nullable: Optional display name. Public Parse, Split, Classify, Extract, and Ground runs use a stable server default when blank. The console calls a named run a 'project'. - `options` GroundOptionsOutput - `include_previews` boolean: When true, matches include cropped_image_url for visual regions. Fetch with the same API key. - `max_matches` integer: Maximum matches to return per target, ranked best-first. An HTML source is capped the same way, but only visible rendered text is matched: text hidden by its own style attribute, a hidden or aria-hidden attribute, or an unopened is never returned. Hiding that comes from a stylesheet or a media query is not evaluated. A hint ranks the visible occurrence nearest that nearby text first; without a hint, rank 1 is the first visible occurrence. - `minimum_semantic_score` number, nullable: Deprecated minimum score for semantic and model-scored matches. The exact-match PDF, Word and PowerPoint runtime ignores it: a semantic pick there is kept only when the model rates it above no answer. Exact and normalized matches are unaffected. - `require_visual_region` boolean: When true, only matches that have a visual region are kept. Not supported by the current runtime. - `use_word_level_grounding` boolean: Experimental. Match targets against word-level OCR bboxes. PDF sources only. Targets shorter than 2 normalized characters return status failed with error needle_too_short. - `output_workspace_id` string, uuid, nullable: Workspace for retained result artifacts. Defaults to the unique source workspace, or a reused Parse's output workspace. Required for ambiguous destinations involving customer storage. Does not change source access. - `parse` GroundParseSettings: Settings for the shared Parse Ground reads. Ground has no high mode: it bills per target, not per page. - `diagrams` ParseDiagramsOptions - `mode` 'omit' | 'mermaid': Whether flowchart-like figures stay as images or are rewritten as Mermaid fences. - `figures` ParseSettingsFigures: How figure regions are kept in the Parse behind an operation. - `mode` 'omit' | 'include' | 'describe', required: omit drops figure regions from the Parse this operation reads. include and describe both keep them and are the default: the operation reads the same Parse for either. - `page_ranges` PageRange[], nullable: One-based inclusive pages to read, as page_ranges on Parse. On an operation with its own page_ranges the two must agree. With a parse_result source it keeps only those pages of the reused Parse. - `end` integer, required: Last page of the range, 1-based and inclusive. - `start` integer, required: First page of the range, 1-based and inclusive. - `parse_mode` 'low' | 'medium', nullable: Parsing effort for the Parse Ground reads: low (the default) or medium. high is not accepted. - `spreadsheet` ParseSpreadsheetOptions: Workbook-specific Parse controls for spreadsheet sources. Defaults preserve the pre-control behavior: every sheet/row/column is included and formula *source text* is omitted (cached values still appear). - `include_formulas` boolean: When true, include formula source text. Cached calculated values are always present. - `include_hidden_columns` boolean: When false, skip columns marked hidden. - `include_hidden_rows` boolean: When false, skip rows marked hidden. - `include_hidden_sheets` boolean: When false, skip sheets marked hidden in the workbook. - `sheets` string[], nullable: Optional sheet-name filter. When set, only listed sheets are parsed, in workbook order. - `project_id` string, uuid, nullable: Caller-minted grouping id; jobs submitted together share it. Not a server-side resource. - `request_type` 'ground' - `source` union, required: The document to search: a fresh upload, an HTTPS URL, a workspace file, or a prior parse job. - 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. - `file_name` string, required: Filename to record for the fetched bytes. - `type` 'url' - `url` string, required: HTTPS URL the service fetches. - 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. - `file_id` string, uuid, required: File id from GET /v1/workspaces/{workspace_id}/files. - `type` 'workspace_file' - `workspace_id` string, uuid, required: Workspace that owns the file. - ParseResultSource: A prior Parse job whose parsed artifact can be reused by downstream methods. - `job_id` string, uuid, required: Succeeded parse job whose artifact should be reused. - `type` 'parse_result' - `targets` GroundTarget[], nullable: Quoted strings to locate, up to 30. Exactly one of claims or targets must be set. - `hint` string, nullable: Nearby free-text context that helps disambiguate a repeated quote. - `id` string, required: Caller-defined id echoed on the matching result target. - `page_hints` integer[], nullable: Optional 1-based pages to search first. - `semantic` boolean: When true, text is a description of what to find, not a quote. On deployments that ground PDF, Word and PowerPoint sources with the exact-match runtime, the description picks up to max_matches sentences, table cells, lines, blocks, sections (a heading with its text) or table rows that answer it, best first, and each comes back as an exact match with match_method semantic. hint steers the pick. A target whose answer is not in the source comes back not found. On those deployments, if the picking model is unavailable, the target fails with error native_2_semantic_unavailable. Use false for exact text matching. - `sheet` string, nullable: Workbook tab to search. Ignored for non-spreadsheet sources. - `text` string, required: Quoted string to locate in the source. ## Other responses - `504`: Gateway Timeout - `default`: Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code. --- [API](https://skmtc.dev/nace/apis/ndi-platform-api.md) - [All operations](https://skmtc.dev/nace/apis/ndi-platform-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/ndi-platform-api/revisions/d002a3589a67?raw)