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": [
          {
            "name": "*"
          }
        ],
        "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": [
          {
            "name": "*"
          }
        ],
        "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": [
          {
            "name": "*"
          }
        ],
        "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": [
          {
            "name": "*"
          }
        ],
        "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": [
          {
            "name": "*"
          }
        ],
        "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.
KnowledgeBaseAzureBlobReference

Represents an Azure Blob Storage document reference.
KnowledgeBaseErrorAdditionalInfo

The resource management error additional info.
KnowledgeBaseErrorDetail

The error details.
KnowledgeBaseImageContent

Image content.
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.
KnowledgeBaseSearchIndexReference

Represents an Azure Search document reference.
KnowledgeBaseWebReference

Represents a web document reference.
KnowledgeRetrievalIntentType

The kind of knowledge base configuration to use.
KnowledgeRetrievalMinimalReasoningEffort

Run knowledge retrieval with minimal reasoning effort.
KnowledgeRetrievalReasoningEffortKind

The amount of effort to use during retrieval.
KnowledgeRetrievalSemanticIntent

A semantic query intent.
KnowledgeSourceKind

The kind of the knowledge source.
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

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

Web retrieval activity.
modelWebSummarization

LLM web summarization activity.
agenticReasoning

Agentic reasoning activity.

KnowledgeBaseAgenticReasoningActivityRecord

Object

Represents an agentic reasoning activity record.

Name Type Description
elapsedMs

integer (int32)

The elapsed time in milliseconds for the retrieval activity.
error

KnowledgeBaseErrorDetail

The error detail explaining why the operation failed. This property is only included when the activity does not succeed.
id

integer (int32)

The ID of the activity record.
reasoningTokens

integer (int32)

The number of input tokens for agentic reasoning.
retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

KnowledgeRetrievalMinimalReasoningEffort

The retrieval reasoning effort configuration.
type string:

agenticReasoning

The type of the activity record.

KnowledgeBaseAzureBlobReference

Object

Represents an Azure Blob Storage document reference.

Name Type Description
activitySource

integer (int32)

The source activity ID for the reference.
blobUrl

string

The blob URL for the reference.
id

string

The ID of the reference.
rerankerScore

number (float)

The reranker score for the document reference.
sourceData

The source data for the reference.
type string:

azureBlob

The type of the reference.

KnowledgeBaseErrorAdditionalInfo

Object

The resource management error additional info.

Name Type Description
info

The additional info.
type

string

The additional info type.

KnowledgeBaseErrorDetail

Object

The error details.

Name Type Description
additionalInfo

KnowledgeBaseErrorAdditionalInfo[]

The error additional info.
code

string

The error code.
details

KnowledgeBaseErrorDetail[]

The error details.
message

string

The error message.
target

string

The error target.

KnowledgeBaseImageContent

Object

Image content.

Name Type Description
url

string (uri)

The url of the image.

KnowledgeBaseIndexedOneLakeReference

Object

Represents an indexed OneLake document reference.

Name Type Description
activitySource

integer (int32)

The source activity ID for the reference.
docUrl

string

The document URL for the reference.
id

string

The ID of the reference.
rerankerScore

number (float)

The reranker score for the document reference.
sourceData

The source data for the reference.
type string:

indexedOneLake

The type of the reference.

KnowledgeBaseMessage

Object

The natural language message style object.

Name Type Description
content KnowledgeBaseMessageContent[]:

The content of the message.
role

string

The role of the tool response.

KnowledgeBaseMessageContentType

Enumeration

The type of message content.

Value Description
text

Text message content kind.
image

Image message content kind.

KnowledgeBaseMessageImageContent

Object

Image message type.

Name Type Description
image

KnowledgeBaseImageContent

The image content.
type string:

image

The type of the message

KnowledgeBaseMessageTextContent

Object

Text message type.

Name Type Description
text

string

The text content.
type string:

text

The type of the message

KnowledgeBaseModelWebSummarizationActivityRecord

Object

Represents an LLM web summarization activity record.

Name Type Description
elapsedMs

integer (int32)

The elapsed time in milliseconds for the retrieval activity.
error

KnowledgeBaseErrorDetail

The error detail explaining why the operation failed. This property is only included when the activity does not succeed.
id

integer (int32)

The ID of the activity record.
inputTokens

integer (int32)

The number of input tokens for the LLM web summarization activity.
outputTokens

integer (int32)

The number of output tokens for the LLM web summarization activity.
type string:

modelWebSummarization

The type of the activity record.

KnowledgeBaseReferenceType

Enumeration

The type of reference.

Value Description
searchIndex

Search index document reference.
azureBlob

Azure Blob document reference.
indexedOneLake

Indexed OneLake document reference.
web

Web document reference.

KnowledgeBaseRetrievalRequest

Object

The input contract for the retrieval request.

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.

KnowledgeBaseRetrievalResponse

Object

The output contract for the retrieval response.

Name Type Description
activity KnowledgeBaseActivityRecord[]:

The activity records for tracking progress and billing implications.
references KnowledgeBaseReference[]:

The references for the retrieval data used in the response.
response

KnowledgeBaseMessage[]

The response messages.

KnowledgeBaseSearchIndexReference

Object

Represents an Azure Search document reference.

Name Type Description
activitySource

integer (int32)

The source activity ID for the reference.
docKey

string

The document key for the reference.
id

string

The ID of the reference.
rerankerScore

number (float)

The reranker score for the document reference.
sourceData

The source data for the reference.
type string:

searchIndex

The type of the reference.

KnowledgeBaseWebReference

Object

Represents a web document reference.

Name Type Description
activitySource

integer (int32)

The source activity ID for the reference.
id

string

The ID of the reference.
rerankerScore

number (float)

The reranker score for the document reference.
sourceData

The source data for the reference.
title

string

The title of the web document.
type string:

web

The type of the reference.
url

string (uri)

The url the reference data originated from.

KnowledgeRetrievalIntentType

Enumeration

The kind of knowledge base configuration to use.

Value Description
semantic

A natural language semantic query intent.

KnowledgeRetrievalMinimalReasoningEffort

Object

Run knowledge retrieval with minimal reasoning effort.

Name Type Description
kind string:

minimal

The kind of reasoning effort.

KnowledgeRetrievalReasoningEffortKind

Enumeration

The amount of effort to use during retrieval.

Value Description
minimal

Does not perform any source selections, query planning, or iterative search.

KnowledgeRetrievalSemanticIntent

Object

A semantic query intent.

Name Type Description
search

string

The semantic query to execute
type string:

semantic

The type of the intent.

KnowledgeSourceKind

Enumeration

The kind of the knowledge source.

Value Description
searchIndex

A knowledge source that reads data from a Search Index.
azureBlob

A knowledge source that read and ingest data from Azure Blob Storage to a Search Index.
indexedOneLake

A knowledge source that reads data from indexed OneLake.
web

A knowledge source that reads data from the web.

SearchIndexKnowledgeSourceParams

Object

Specifies runtime parameters for a search index knowledge source

Name Type Description
filterAddOn

string

A filter condition applied to the index (e.g., 'State eq VA').
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:

searchIndex

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.

WebKnowledgeSourceParams

Object

Specifies runtime parameters for a web knowledge source

Name Type Description
count

integer (int32)

The number of web results to return.
freshness

string

The freshness of web results.
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:

web

The type of the knowledge source.
knowledgeSourceName

string

The name of the index the params apply to.
language

string

The language of the web results.
market

string

The market of the web results.
rerankerThreshold

number (float)

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