Knowledge Retrieval - Retrieve

Service:
Search Service
API Version:
2026-04-01

KnowledgeBase retrieves relevant data from backing stores.

POST {endpoint}/knowledgebases('{knowledgeBaseName}')/retrieve?api-version=2026-04-01

URI Parameters

Name In Required Type Description
endpoint
 path True

string (uri)

The endpoint URL of the search service.
knowledgeBaseName
 path True

string

The name of the knowledge base.
api-version
 query True

string

minLength: 1

The API version to use for this operation.

Request Header

Name Required Type Description
Accept

Accept

The Accept header.
x-ms-client-request-id

string (uuid)

An opaque, globally-unique, client-generated string identifier for the request.

Request Body

Name Type Description
includeActivity

boolean

Indicates retrieval results should include activity information.
intents KnowledgeRetrievalIntent[]:

KnowledgeRetrievalSemanticIntent[]

A list of intended queries to execute without model query planning.
knowledgeSourceParams KnowledgeSourceParams[]:

A list of runtime parameters for the knowledge sources.
maxOutputSizeInTokens

integer (int32)

Limits the maximum size of the content in the output.
maxRuntimeInSeconds

integer (int32)

The maximum runtime in seconds.

Responses

Name Type Description
200 OK

KnowledgeBaseRetrievalResponse

Successful retrieval response.
Other Status Codes

KnowledgeBaseRetrievalResponse

Partial retrieval response.
Other Status Codes

ErrorResponse

An unexpected error response.

Security

api-key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Scopes

Name Description
https://search.azure.com/.default

Examples

KnowledgeBaseRetrieve
KnowledgeBaseRetrieveWithIntents

KnowledgeBaseRetrieve

Sample request

POST https://exampleservice.search.windows.net/knowledgebases('base-example-index')/retrieve?api-version=2026-04-01


{
  "maxRuntimeInSeconds": 60,
  "maxOutputSizeInTokens": 100000,
  "includeActivity": true,
  "knowledgeSourceParams": [
    {
      "filterAddOn": "foo eq bar",
      "knowledgeSourceName": "ks-example-index",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "rerankerThreshold": 2.1,
      "kind": "searchIndex"
    }
  ]
}

Sample response

Status code:
200 
{
  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 11,
      "outputTokens": 22,
      "elapsedMs": 10
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "ks-example-index",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world",
        "filter": "foo eq bar",
        "sourceDataFields": [
          {
            "name": "category"
          },
          {
            "name": "description"
          },
          {
            "name": "ownerId"
          },
          {
            "name": "id"
          }
        ],
        "searchFields": [],
        "semanticConfigurationName": "testconfig"
      }
    },
    {
      "type": "searchIndex",
      "id": 2,
      "knowledgeSourceName": "ks-example-index",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world two",
        "filter": "foo eq bar",
        "sourceDataFields": [
          {
            "name": "category"
          },
          {
            "name": "description"
          },
          {
            "name": "ownerId"
          },
          {
            "name": "id"
          }
        ],
        "searchFields": [],
        "semanticConfigurationName": "testconfig"
      }
    },
    {
      "type": "agenticReasoning",
      "id": 3,
      "reasoningTokens": 74
    },
    {
      "type": "modelAnswerSynthesis",
      "id": 4,
      "inputTokens": 664,
      "outputTokens": 1328,
      "elapsedMs": 10
    }
  ],
  "references": [
    {
      "type": "searchIndex",
      "id": "83dd7d40",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      },
      "rerankerScore": 3.5,
      "docKey": "myDocKey1"
    },
    {
      "type": "searchIndex",
      "id": "83dd7d41",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      },
      "rerankerScore": 2.7,
      "docKey": "myDocKey2"
    }
  ]
}
Status code:
206 
{
  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelQueryPlanning",
      "id": 0,
      "inputTokens": 11,
      "outputTokens": 22,
      "elapsedMs": 10
    },
    {
      "type": "searchIndex",
      "id": 1,
      "knowledgeSourceName": "ks-example-index",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "hello world",
        "filter": "foo eq bar",
        "sourceDataFields": [
          {
            "name": "category"
          },
          {
            "name": "description"
          },
          {
            "name": "ownerId"
          },
          {
            "name": "id"
          }
        ],
        "searchFields": [],
        "semanticConfigurationName": "testconfig"
      }
    },
    {
      "type": "web",
      "id": 2,
      "knowledgeSourceName": "ks-preview-web",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 10,
      "elapsedMs": 2345,
      "error": {
        "code": "403",
        "message": "The error message",
        "details": [],
        "additionalInfo": [
          {
            "type": "SomeErrorType",
            "info": {
              "someProperty": "Some value"
            }
          }
        ]
      }
    },
    {
      "type": "agenticReasoning",
      "id": 3,
      "reasoningTokens": 74
    },
    {
      "type": "modelAnswerSynthesis",
      "id": 4,
      "inputTokens": 664,
      "outputTokens": 1328,
      "elapsedMs": 10
    }
  ],
  "references": [
    {
      "type": "searchIndex",
      "id": "83dd7d40",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      },
      "rerankerScore": 3.5,
      "docKey": "myDocKey1"
    },
    {
      "type": "searchIndex",
      "id": "83dd7d41",
      "activitySource": 1,
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      },
      "rerankerScore": 2.7,
      "docKey": "myDocKey2"
    }
  ]
}

KnowledgeBaseRetrieveWithIntents

Sample request

POST https://exampleservice.search.windows.net/knowledgebases('base-example-index')/retrieve?api-version=2026-04-01


{
  "intents": [
    {
      "search": "foo",
      "type": "semantic"
    }
  ],
  "maxRuntimeInSeconds": 60,
  "maxOutputSizeInTokens": 100000,
  "includeActivity": true,
  "knowledgeSourceParams": [
    {
      "filterAddOn": "foo eq bar",
      "knowledgeSourceName": "ks-example-index",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "rerankerThreshold": 2.1,
      "kind": "searchIndex"
    }
  ]
}

Sample response

Status code:
200 
{
  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "searchIndex",
      "id": 0,
      "knowledgeSourceName": "ks-example-index",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "foo",
        "filter": "foo eq bar",
        "sourceDataFields": [
          {
            "name": "category"
          },
          {
            "name": "description"
          },
          {
            "name": "ownerId"
          },
          {
            "name": "id"
          }
        ],
        "searchFields": [],
        "semanticConfigurationName": "testconfig"
      }
    },
    {
      "type": "agenticReasoning",
      "id": 1,
      "reasoningTokens": 37
    }
  ],
  "references": [
    {
      "type": "searchIndex",
      "id": "83dd7d40",
      "activitySource": 0,
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      },
      "rerankerScore": 3.5,
      "docKey": "myDocKey1"
    },
    {
      "type": "searchIndex",
      "id": "83dd7d41",
      "activitySource": 0,
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      },
      "rerankerScore": 2.7,
      "docKey": "myDocKey2"
    }
  ]
}
Status code:
206 
{
  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "[{...}]"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "searchIndex",
      "id": 0,
      "knowledgeSourceName": "ks-example-index",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 2,
      "elapsedMs": 1234,
      "searchIndexArguments": {
        "search": "foo",
        "filter": "foo eq bar",
        "sourceDataFields": [
          {
            "name": "category"
          },
          {
            "name": "description"
          },
          {
            "name": "ownerId"
          },
          {
            "name": "id"
          }
        ],
        "searchFields": [],
        "semanticConfigurationName": "testconfig"
      }
    },
    {
      "type": "web",
      "id": 1,
      "knowledgeSourceName": "ks-preview-web",
      "queryTime": "2025-01-01T00:08:45.045Z",
      "count": 10,
      "elapsedMs": 2345,
      "error": {
        "code": "403",
        "message": "The error message",
        "details": [],
        "additionalInfo": [
          {
            "type": "SomeErrorType",
            "info": {
              "someProperty": "Some value"
            }
          }
        ]
      }
    },
    {
      "type": "agenticReasoning",
      "id": 2,
      "reasoningTokens": 37
    }
  ],
  "references": [
    {
      "type": "searchIndex",
      "id": "83dd7d40",
      "activitySource": 0,
      "sourceData": {
        "id": "myDocKey1",
        "title": "high_doc",
        "content": "hello world"
      },
      "rerankerScore": 3.5,
      "docKey": "myDocKey1"
    },
    {
      "type": "searchIndex",
      "id": "83dd7d41",
      "activitySource": 0,
      "sourceData": {
        "id": "myDocKey2",
        "title": "low_doc",
        "content": "goodbye world"
      },
      "rerankerScore": 2.7,
      "docKey": "myDocKey2"
    }
  ]
}

Definitions

Name Description
Accept

The Accept header.
AzureBlobKnowledgeSourceParams

Specifies runtime parameters for a azure blob knowledge source
ErrorAdditionalInfo

The resource management error additional info.
ErrorDetail

The error detail.
ErrorResponse

Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
IndexedOneLakeKnowledgeSourceParams

Specifies runtime parameters for a indexed OneLake knowledge source
KnowledgeBaseActivityRecordType

The type of activity record.
KnowledgeBaseAgenticReasoningActivityRecord

Represents an agentic reasoning activity record.
KnowledgeBaseAzureBlobActivityArguments

Represents the arguments the azure blob retrieval activity was run with.
KnowledgeBaseAzureBlobActivityRecord

Represents a azure blob retrieval activity record.
KnowledgeBaseAzureBlobReference

Represents an Azure Blob Storage document reference.
KnowledgeBaseErrorAdditionalInfo

The resource management error additional info.
KnowledgeBaseErrorDetail

The error details.
KnowledgeBaseImageContent

Image content.
KnowledgeBaseIndexedOneLakeActivityArguments

Represents the arguments the indexed OneLake retrieval activity was run with.
KnowledgeBaseIndexedOneLakeActivityRecord

Represents a indexed OneLake retrieval activity record.
KnowledgeBaseIndexedOneLakeReference

Represents an indexed OneLake document reference.
KnowledgeBaseMessage

The natural language message style object.
KnowledgeBaseMessageContentType

The type of message content.
KnowledgeBaseMessageImageContent

Image message type.
KnowledgeBaseMessageTextContent

Text message type.
KnowledgeBaseModelWebSummarizationActivityRecord

Represents an LLM web summarization activity record.
KnowledgeBaseReferenceType

The type of reference.
KnowledgeBaseRetrievalRequest

The input contract for the retrieval request.
KnowledgeBaseRetrievalResponse

The output contract for the retrieval response.
KnowledgeBaseSearchIndexActivityArguments

Represents the arguments the search index retrieval activity was run with.
KnowledgeBaseSearchIndexActivityRecord

Represents a search index retrieval activity record.
KnowledgeBaseSearchIndexReference

Represents an Azure Search document reference.
KnowledgeBaseWebActivityArguments

Represents the arguments the web retrieval activity was run with.
KnowledgeBaseWebActivityRecord

Represents a web retrieval activity record.
KnowledgeBaseWebReference

Represents a web document reference.
KnowledgeRetrievalIntentType

The kind of knowledge base configuration to use.
KnowledgeRetrievalSemanticIntent

A semantic query intent.
KnowledgeSourceKind

The kind of the knowledge source.
SearchIndexFieldReference

Field reference for a search index.
SearchIndexKnowledgeSourceParams

Specifies runtime parameters for a search index knowledge source
WebKnowledgeSourceParams

Specifies runtime parameters for a web knowledge source

Accept

Enumeration

The Accept header.

Value Description
application/json;odata.metadata=minimal

AzureBlobKnowledgeSourceParams

Object

Specifies runtime parameters for a azure blob knowledge source

Name Type Description
includeReferenceSourceData

boolean

Indicates whether references should include the structured data obtained during retrieval in their payload.
includeReferences

boolean

Indicates whether references should be included for data retrieved from this source.
kind string:

azureBlob

The type of the knowledge source.
knowledgeSourceName

string

The name of the index the params apply to.
rerankerThreshold

number (float)

The reranker threshold all retrieved documents must meet to be included in the response.

ErrorAdditionalInfo

Object

The resource management error additional info.

Name Type Description
info

searchservice.knowledgeretrieval.retrieve

The additional info.
type

string

The additional info type.

ErrorDetail

Object

The error detail.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

The error additional info.
code

string

The error code.
details

ErrorDetail[]

The error details.
message

string

The error message.
target

string

The error target.

ErrorResponse

Object

Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).

Name Type Description
error

ErrorDetail

The error object.

IndexedOneLakeKnowledgeSourceParams

Object

Specifies runtime parameters for a indexed OneLake knowledge source

Name Type Description
includeReferenceSourceData

boolean

Indicates whether references should include the structured data obtained during retrieval in their payload.
includeReferences

boolean

Indicates whether references should be included for data retrieved from this source.
kind string:

indexedOneLake

The type of the knowledge source.
knowledgeSourceName

string

The name of the index the params apply to.
rerankerThreshold

number (float)

The reranker threshold all retrieved documents must meet to be included in the response.

KnowledgeBaseActivityRecordType

Enumeration

The type of activity record.

Value Description
searchIndex

Search index retrieval activity.
azureBlob

Azure Blob retrieval activity.
indexedOneLake

Indexed OneLake retrieval activity.
web