> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Ground

> Pin quoted text to a location in the source

Ground is target location, not claim verification. Pass 1–30 targets.

```ts theme={"dark"}
import { NdiClient } 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" }],
      wait_seconds: 30,
    })
  ).job_id,
);
if (job.result?.result_type === "ground" && "targets" in job.result) {
  for (const target of job.result.targets) {
    for (const match of target.matches ?? []) {
      console.log(target.id, match.matched_text, match.location);
    }
  }
}
```

## Method signature

```text theme={"dark"}
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      | File or prior parse                   |
| `opts.targets`      | `GroundTarget[]`                     | Yes      | 1–30 quoted strings                   |
| `opts.options`      | `GroundOptions`                      | No       | `max_matches`, `include_previews`     |
| `opts.wait_seconds` | `number`                             | No       | Hold the HTTP response open (max 300) |

### Returns

A `Job`. On success, `result.targets[].matches` carries locators. `not_found`
is an answer about the document.

Set `options.include_previews` to mint crop URLs. Fetch them with
`client.jobs.groundCrop(job_id, artifact_ref)`.

See [Ground guide](/guides/ground) and [Ground response](/guides/ground-response).