Job-scoped Search
Searches retrieval-indexed crawled content produced by one named job to find evidence relevant to a question
Requires the Dapi Retrieval feature.
Endpoint
POST /api/v3/jobs/{jobName}/retrieve
Path Parameters
| Name | Type | Description |
|---|---|---|
| jobName | string | Required. Unique job name within the tenant. Reuse the same value to manage job config, start crawls, fetch URLs, inspect tasks and Traversal runs, and query indexed data |
Request Body
Required application/json body containing a RetrieveRequest.
Similarity Thresholds
Choose a preset for quick, predictable relevance, or provide a numeric value. Presets map to cosine similarity scores.
| Name | When to use |
|---|---|
| exact-match | The query and result describe essentially the same thing, exact term, or strong synonym. |
| same-category | Not identical, but clearly the same family/category and very relevant. |
| same-domain | Topically aligned within the same thematic domain; balanced recall vs. precision. |
| generic-similarity | Broad lexical similarity; maximize recall when you will filter results later. |
Responses
200 (OK)
Returns RetrievalItem[] as an array of RetrievalItem.
400 (Bad Request)
Invalid request parameters. Refer to the response text for more information.
403 (Forbidden)
Access restricted. Refer to the response text for more information
404 (Not Found)
The specified job was not found.
500 (Internal Server Error)
The retrieval operation failed in a backing service. Refer to the response text for more information.
Data Contracts
RetrieveRequest
Defines a semantic retrieval query, result limit, and score threshold for indexed crawled content
Fields:
| Name | Type | Description |
|---|---|---|
| Query | string | Search query used to find relevant indexed content chunks |
| Limit | int or null | Optional. Maximum number of retrieval results to return. Omitted or null uses 10 |
| Threshold | string or null | Optional. Retrieval score threshold. Use an invariant-culture float from 0 to 1 or one of: exact-match, same-category, same-domain, generic-similarity. Omitted, null, or unrecognized text uses same-domain |
RetrievalItem
One matched indexed content chunk returned by retrieval
Fields:
| Name | Type | Description |
|---|---|---|
| Score | float | Relevance score for this retrieval match; higher values are returned first |
| Span | string | Matched text span with semantic context |
| DownloadTasks | array of DownloadTaskInfo | Downloaded pages that contain the matched text |
DownloadTaskInfo
Source download task for a retrieval match
Fields:
| Name | Type | Description |
|---|---|---|
| DownloadTaskId | string | Download task ID |
| Url | string | Source page URL |
| CaptureDateUtc | datetime | Date and time when the source page was captured, in UTC |