Ground response format - NDI Platform API

A succeeded ground job has result.result_type: "ground". There is one entry in result.targets per request target, in request order.

{
  "result_type": "ground",
  "targets": [
    {
      "id": "total",
      "status": "found",
      "matches": [
        {
          "rank": 1,
          "matched_text": "1,200.50",
          "match_method": "normalized",
          "confidence": null,
          "location": { "kind": "text_span", "page": 1, "char_start": 120, "char_end": 128 },
          "cropped_image_url": null
        }
      ]
    }
  ],
  "units": 1
}

Targets

Field	Meaning
`id`	Caller-defined id from the request `targets` list. Join request to result on this, not on the quote text
`status`	Per-target outcome. `found` has at least one location. `not_found` means the quote is not in the document — the job still succeeded. `failed` means this target errored; see `error`
`matches`	Locations for this target, already sorted best-first and numbered by `rank`. Empty when status is `not_found`
`error`	Machine-readable reason when `status` is `failed` (for example `needle_too_short`). Null otherwise

not_found is success about the document, not a job failure. The job status is still succeeded.

Matches

Field	Meaning
`rank`	1-based position of this hit in `matches` for this target. The matcher sorts locations before the result is built, so `1` is the primary place to use and later ranks are other occurrences or weaker hits of the same quote. 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, and a phrase in a figure caption can come before the same phrase in the prose. Rank restarts at `1` on every target. The list is truncated at `options.max_matches` (default 10). `rank` is not a score — quality lives on `match_method` and, when the provider reports one, `confidence`
`matched_text`	The string actually found at `location`. Can differ from the request `text` when `match_method` is `normalized` or `semantic`
`match_method`	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, including a JSON hit that used the query improver
`confidence`	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`	Where the quote was found. Kind follows the source: `page_region` (PDF or image polygons), `text_span` (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` (workbook tab and A1), `json_pointer` (JSON key, scalar, number, string fragment, or structural subset pattern), `jsonl_record` (JSONL line), `row_range` (table rows), or `audio_range` (media timestamps)
`cropped_image_url`	Authenticated crop of a visual region when `options.include_previews` is true. Fetch with the same API key. Null when previews were off or the hit has no visual region

Fetch a crop with the same X-API-Key via client.jobs.ground_crop or GET /v1/jobs/{job_id}/ground-crops/{artifact_ref}.

Ground crops — GET /v1/jobs/{job_id}/ground-crops/{artifact_ref}
Ground transcripts — GET /v1/jobs/{job_id}/ground-transcript/{artifact_ref}. Ground audio/video only; parse jobs use /parse-transcript
Converted PDF — GET /v1/jobs/{job_id}/converted-pdf/{artifact_ref}
Spreadsheet cell maps — GET /v1/jobs/{job_id}/spreadsheet-cell-maps/{artifact_ref}