Ground

documents.ground finds supplied text in a document and returns source locations. Use it to connect a value or quote back to evidence.

Ground locates text. It does not determine whether a claim is true.

Basic usage

import { NdiClient, UnknownResult, type GroundTarget } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const queued = await client.documents.ground(upload, {
  targets: [
    { id: "revenue", text: "$12.4 million" },
    { id: "period", text: "year ended December 31, 2025" },
  ],
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: succeeded Job; job.result is a GroundResult

if (job.result?.result_type === "ground" && !(job.result instanceof UnknownResult)) {
  for (const target of job.result.targets) {
    for (const match of target.matches ?? []) {
      console.log(target.id, match.matched_text, match.location);
    }
  }
}

Method signature

ground(
  source: DocumentSource | UploadResponse,
  opts: {
    targets: GroundTarget[];
    options?: GroundOptions;
    wait_seconds?: number;
    idempotency_key?: string;
  },
): Promise<Job>

Parameters

Parameter	Type	Required	Description
`source`	`DocumentSource` or `UploadResponse`	Yes	Staged upload, URL, workspace file, or successful parse job
`opts.targets`	`GroundTarget[]`	Yes	1–30 quoted strings to locate
`opts.options`	`GroundOptions`	No	Match cap, semantic threshold, and preview URLs
`opts.wait_seconds`	`number`	No	Hold the submission request open for up to 300 seconds
`opts.idempotency_key`	`string`	No	Override the key the SDK normally mints

Returns

A Job. After success, job.result is a GroundResult:

Field	Description
`targets`	One result per request target, in request order
`units`	Billable units
`transcript_url`	Authenticated grounding transcript for supported media

Define targets

Every target needs an ID and the text to locate:

import { type GroundTarget } from "ndi-sdk";

const targets: GroundTarget[] = [
  {
    id: "contract_value",
    text: "$1,200,000",
  },
  {
    id: "effective_date",
    text: "January 1, 2026",
  },
];

The ID is echoed in the result. Join request targets to results by id, not by quoted text.

Disambiguate repeated text

Add nearby context with hint:

import { type GroundTarget } from "ndi-sdk";

const target: GroundTarget = {
  id: "ending_balance",
  text: "$48,921.10",
  hint: "Ending balance in the account summary",
};

On HTML sources, the visible occurrence nearest the hint ranks first. Without a hint, the first visible occurrence ranks first.

Match by meaning (deprecated)

semantic is deprecated for now. Don’t rely on it: a target with semantic: true can come back with status failed and error semantic_mode_deprecated. Quote the text exactly as it appears in the source.

Select a worksheet

Use sheet to narrow a workbook target to one tab:

import { type GroundTarget } from "ndi-sdk";

const target: GroundTarget = {
  id: "net_income",
  text: "4,821,000",
  sheet: "Income Statement",
};

sheet is ignored for non-spreadsheet sources.

Configure matching

import { type GroundOptions } from "ndi-sdk";

const options: GroundOptions = {
  max_matches: 5,
  minimum_semantic_score: 0.8,
  include_previews: true,
};

Option	Default	Description
`max_matches`	`10`	Maximum matches per target, ranked best-first. Accepts 1–50
`minimum_semantic_score`	none	Drop semantic matches below this 0–1 score
`include_previews`	`false`	Mint crop URLs for matches with visual regions

minimum_semantic_score does not affect exact or normalized matches. require_visual_region exists in the model but is not supported by the current runtime; do not enable it.

Response structure

Each target has an independent outcome:

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const job = await client.jobs.wait("ground-job-id");
// Returns: succeeded ground job

if (job.result?.result_type === "ground" && !(job.result instanceof UnknownResult)) {
  const result = job.result;

  for (const target of result.targets) {
    console.log(target.id);
    console.log(target.status);    // "found", "not_found", or "failed"
    console.log(target.error);     // set only when this target failed

    for (const match of target.matches ?? []) {
      console.log(match.rank);
      console.log(match.matched_text);
      console.log(match.match_method);
      console.log(match.confidence);
      console.log(match.location);
      console.log(match.cropped_image_url);
    }
  }
}

not_found is a successful answer about the document; the job itself remains succeeded. failed means that target encountered an error. Matches are sorted best-first:

Field	Description
`rank`	One-based position for this target. It is not a confidence score
`matched_text`	Text found at the returned location
`match_method`	`"exact"`, `"normalized"`, or `"semantic"`
`confidence`	Optional 0–1 locator confidence
`location`	Typed source locator
`cropped_image_url`	Authenticated preview when requested and available

Location types

The location model follows the source:

`location.kind`	Source location
`page_region` / `visual_region`	Page and normalized polygons
`sheet_range` / `spreadsheet_range`	Worksheet and A1 range
`text_span` / `text_range`	Character offsets
`row_range`	Table rows and optional column
`jsonl_record`	JSONL record index
`audio_range`	Start and end timestamps
`json_pointer`	RFC 6901 pointer into a JSON document

Ground response format

Review target status, ranking, match methods, locator fields, and related artifacts.

Preview visual matches

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const job = await client.jobs.wait(
  (
    await client.documents.ground(upload, {
      targets: [{ id: "total", text: "$1,200.50" }],
      options: { include_previews: true },
      wait_seconds: 30,
    })
  ).job_id,
);
// Returns: GroundResult with crop references where visual regions exist

if (job.result?.result_type === "ground" && !(job.result instanceof UnknownResult)) {
  const match = job.result.targets[0]?.matches?.[0];
  console.log(match?.cropped_image_url);
}

The URL is authenticated and short-lived. Pass it directly to jobs.groundCrop to fetch the bytes through the SDK:

import { NdiClient, UnknownResult } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const job = await client.jobs.wait(
  (
    await client.documents.ground(upload, {
      targets: [{ id: "total", text: "$1,200.50" }],
      options: { include_previews: true },
      wait_seconds: 30,
    })
  ).job_id,
);
if (job.result?.result_type === "ground" && !(job.result instanceof UnknownResult)) {
  const match = job.result.targets[0]?.matches?.[0];
  if (match?.cropped_image_url != null) {
    const crop = await client.jobs.groundCrop(job.job_id, match.cropped_image_url);
    // Returns: Uint8Array of crop bytes
  }
}

Do not construct an artifact reference. The SDK accepts the complete returned URL and extracts its reference.

Reuse a parse

import { NdiClient } from "ndi-sdk";

const client = new NdiClient();
const upload = await client.documents.createUpload("report.pdf");
const parsed = await client.jobs.wait(
  (await client.documents.parse(upload, { wait_seconds: 30 })).job_id,
);
const queued = await client.documents.ground(
  { type: "parse_result", job_id: parsed.job_id },
  { targets: [{ id: "total", text: "$1,200.50" }] },
);
// Returns: Job; NDI reuses the successful ParseResult

Complete example

import { NdiClient, UnknownResult, type GroundTarget } from "ndi-sdk";

const targets: GroundTarget[] = [
  {
    id: "revenue",
    text: "$12.4 million",
    hint: "Revenue for the year ended December 31, 2025",
  },
  {
    id: "net_income",
    text: "$2.1 million",
    hint: "Net income in the consolidated statements",
  },
  {
    id: "termination",
    text: "Either party may terminate on thirty days notice",
  },
];

const client = new NdiClient();
const upload = await client.documents.createUpload("annual-report.pdf");
const queued = await client.documents.ground(upload, {
  targets,
  options: {
    max_matches: 3,
    minimum_semantic_score: 0.8,
    include_previews: true,
  },
  wait_seconds: 30,
});
const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
// Returns: GroundResult with one ordered result per target

if (job.result?.result_type === "ground" && !(job.result instanceof UnknownResult)) {
  for (const target of job.result.targets) {
    if (target.status === "found") {
      const best = target.matches?.[0];
      console.log(target.id, best?.matched_text, best?.location);
    } else {
      console.log(target.id, target.status, target.error);
    }
  }
}

Error handling

import { NdiClient, InvalidRequestError, JobFailedError } from "ndi-sdk";

const client = new NdiClient();
try {
  const queued = await client.documents.ground(
    await client.documents.createUpload("report.pdf"),
    { targets: [{ id: "total", text: "$1,200.50" }] },
  );
  const job = await client.jobs.wait(queued.job_id, { timeout: 600 });
  // Returns: succeeded Job, or throws for request/job failure
} catch (err) {
  if (err instanceof InvalidRequestError) {
    console.log(err.code, err.message);
  } else if (err instanceof JobFailedError) {
    console.log(err.job.status, err.job.error);
  }
}

Distinguish a failed job from per-target not_found and failed statuses. Common request errors include an empty target list, more than 30 targets, an unsupported option, or a source the current grounding path cannot read.

Best practices

Use exact source text

Quote the text as written. Semantic matching is deprecated for now.

Add nearby context

Use hint to rank the intended occurrence when a quote repeats.

Join on target ID

Treat the caller-defined ID as the stable key between request and response.

Handle not_found

A missing quote is a successful document-level answer, not an exception.

Get started

Core methods

Async and utilities

Basic usage

Method signature

Parameters

Returns

Define targets

Disambiguate repeated text

Match by meaning (deprecated)

Select a worksheet

Configure matching

Response structure

Location types

Ground response format

Preview visual matches

Reuse a parse

Complete example

Error handling

Best practices

Use exact source text

Add nearby context

Join on target ID

Handle not_found

Next steps

​Basic usage

​Method signature

​Parameters

​Returns

​Define targets

​Disambiguate repeated text

​Match by meaning (deprecated)

​Select a worksheet

​Configure matching

​Response structure

​Location types

Ground response format

​Preview visual matches

​Reuse a parse

​Complete example

​Error handling

​Best practices

Use exact source text

Add nearby context

Join on target ID

Handle not_found

​Next steps

Basic usage

Method signature

Parameters

Returns

Define targets

Disambiguate repeated text

Match by meaning (deprecated)

Select a worksheet

Configure matching

Response structure

Location types

Preview visual matches

Reuse a parse

Complete example

Error handling

Best practices

Next steps