> For the complete documentation index, see [llms.txt](https://docs.contextual.io/documentation-and-resources/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/query-and-use-results.md).

# Query and Use Results

Once your records are indexed, you can search them through the Native Object API. This page explains how to select a Search Profile and named Search Index, submit a query, and interpret results containing matched text or current source records. It also covers how to use those results in your solution while preserving references to the records that support an answer.

## Query Through the Native Object API

Use these endpoints in the Native Object API for your tenant to search the records indexed by a Search Profile. Choose the endpoint that returns either current source records or matching passages from the indexed text. The paths below are relative to the API's base URL.

| Method and Path                   | Result                                                                             |
| --------------------------------- | ---------------------------------------------------------------------------------- |
| `POST /$ai-search/:typeId`        | Current source records corresponding to retrieved hits, deduplicated by record ID. |
| `POST /$ai-search/:typeId/chunks` | Search evidence, including content, source references, projections, and scores.    |

Open the [generated Native Object API reference](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-api.md#generated-reference-and-openapi), then expand the source Object Type used by your Search Profile in the left navigation. Look for the operations whose names begin with **AI search** and end with **records** or **chunks**, depending on the response you need. See [Native Object API](https://docs.contextual.io/documentation-and-resources/tenants/tenant-apis/native-object-api.md) for tenant access guidance.

Use the source Object Type ID as `typeId`. Source read permission is required. These endpoints do not support external Object Types.

Both routes accept this request shape:

```json
{
  "profileId": "equipment-help",
  "indexId": "default",
  "query": "The pump is running but barely moving water.",
  "topK": 10
}
```

Here, `equipment-help` is an example profile ID and `default` is an example named Search Index ID on that profile. Replace them with IDs from your tenant; these names are not created automatically. Use a query that a known record in your source Object Type should answer.

| Field       | Required | Meaning                                                            |
| ----------- | -------- | ------------------------------------------------------------------ |
| `profileId` | Yes      | Profile to search.                                                 |
| `indexId`   | No       | Named preset to apply. Pass it explicitly for repeatable behavior. |
| `query`     | Yes      | Nonempty search text.                                              |
| `topK`      | No       | Candidate limit from 1 to 100; overrides the preset value.         |

Search requests do not accept query-time filters (filter conditions supplied with an individual query). To filter results, configure [static filters](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md#static-filters) on a named index and include its ID in `indexId`.

Requests also do not accept a field-selection list. See [Indexes](https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/concepts-and-configuration.md#indexes) for behavior when `indexId` is omitted.

## Read Search Evidence

The chunks route returns an envelope with `profileId`, optional `indexId`, `generationId`, and `items`. Each hit includes:

| Field                         | Meaning                                               |
| ----------------------------- | ----------------------------------------------------- |
| `recordUri`                   | Reference to the source record.                       |
| `documentId`                  | Identifier used to group a document's hits.           |
| `chunkId`                     | Optional chunk identifier.                            |
| `content`                     | Indexed text returned as evidence.                    |
| `projections`                 | Typed attributes evaluated from the source record.    |
| `score`                       | Retrieval score.                                      |
| `semanticRank`, `keywordRank` | Optional ranks from the retrieval modes.              |
| `rerankScore`                 | Optional score added by reranking.                    |
| `sourceHash`                  | Optional hash identifying the indexed source version. |

A score is not a probability that an answer is correct. Compare the text with the query and source record. Multiple hits can refer to the same document when grouping is disabled.

## Read Source Records

The records route returns a similar envelope, but its `items` contain current source records rather than the evidence-hit structure. Evidence explains a match, while a current record provides the data a solution acts on.

Both routes check that retrieved source records still exist and are available through the route's record checks. Removed records can reduce the returned count. Indexed evidence can still reflect an earlier version of a record during asynchronous updates.

## Use Results in a Solution

Keep the query, profile ID, index ID, and source references when reviewing an answer. Have the consuming client distinguish retrieved facts from its interpretation. Retrieve current source data before taking an action that depends on the record's latest state.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.contextual.io/documentation-and-resources/components-and-data/ai-search/query-and-use-results.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
