Knowledge Retrieval - Retrieve Stream

Retrieves relevant data from backing stores and streams progress and results as server-sent events.

Process the response incrementally using server-sent event framing. Each event contains an event name and a JSON-encoded data payload. The stream ends with either a response.completed event or an error event. OpenAPI 2.0 represents the response body as a string, so generated clients may expose the raw response without typed event parsing. Do not deserialize the complete response body as a single JSON document.

POST {endpoint}/knowledgebases('{knowledgeBaseName}')/retrieve?_overload=retrieveStream&api-version=2026-10-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 True

Accept

The Accept header.

x-ms-query-source-authorization

string (password)

Token identifying the user for which the query is being executed. This token is used to enforce security restrictions on documents.

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.

maxOutputDocuments

integer (int32)

Limits the maximum number of documents in the output.

maxOutputSizeInTokens

integer (int32)

Limits the maximum size of the content in the output.

maxRuntimeInSeconds

integer (int32)

The maximum runtime in seconds.

messages

KnowledgeBaseMessage[]

A list of chat message style input.

outputMode

KnowledgeRetrievalOutputMode

The output configuration for this retrieval.

retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

The retrieval reasoning effort configuration.

Responses

Name Type Description
200 OK

string

The request has succeeded.

Media Types: "text/event-stream", "application/json"

Other Status Codes

ErrorResponse

An unexpected error response.

Media Types: "text/event-stream", "application/json"

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

KnowledgeBaseRetrieveStream

Sample request

POST https://typespecstableexampleservice.search.windows.net/knowledgebases('base-preview-test')/retrieve?_overload=retrieveStream&api-version=2026-10-01




{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "hello world"
        }
      ]
    }
  ],
  "maxRuntimeInSeconds": 60,
  "maxOutputDocuments": 5,
  "maxOutputSizeInTokens": 100000,
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "includeActivity": true,
  "outputMode": "answerSynthesis",
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "ks-stable-test",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "rerankerThreshold": 2.1,
      "kind": "searchIndex",
      "filterAddOn": "foo eq bar"
    }
  ]
}

Sample response

"event: retrieval.started\ndata: {\"requestId\":\"00000000-0000-0000-0000-000000000000\",\"knowledgeBaseName\":\"base-preview-test\",\"outputMode\":\"answerSynthesis\",\"reasoningEffort\":{\"kind\":\"low\"}}\n\nevent: activity.started\ndata: {\"id\":0,\"type\":\"modelQueryPlanning\",\"startedAt\":\"2025-01-01T00:08:45.045Z\"}\n\nevent: activity.completed\ndata: {\"type\":\"modelQueryPlanning\",\"id\":0,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"inputTokens\":11,\"outputTokens\":22,\"elapsedMs\":1234}\n\nevent: activity.started\ndata: {\"id\":1,\"type\":\"searchIndex\",\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"knowledgeSourceName\":\"ks-stable-test\"}\n\nevent: activity.completed\ndata: {\"type\":\"searchIndex\",\"id\":1,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"knowledgeSourceName\":\"ks-stable-test\",\"queryTime\":\"2025-01-01T00:08:45.045Z\",\"count\":2,\"elapsedMs\":1234,\"searchIndexArguments\":{\"search\":\"hello world\",\"filter\":\"(category eq 'news') and (foo eq bar)\",\"semanticConfigurationName\":\"testconfig\",\"sourceDataFields\":[{\"name\":\"category\"},{\"name\":\"description\"},{\"name\":\"ownerId\"},{\"name\":\"id\"}],\"searchFields\":[]}}\n\nevent: activity.started\ndata: {\"id\":2,\"type\":\"searchIndex\",\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"knowledgeSourceName\":\"ks-stable-test\"}\n\nevent: activity.completed\ndata: {\"type\":\"searchIndex\",\"id\":2,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"knowledgeSourceName\":\"ks-stable-test\",\"queryTime\":\"2025-01-01T00:08:45.045Z\",\"count\":2,\"elapsedMs\":1234,\"searchIndexArguments\":{\"search\":\"hello world two\",\"filter\":\"(category eq 'news') and (foo eq bar)\",\"semanticConfigurationName\":\"testconfig\",\"sourceDataFields\":[{\"name\":\"category\"},{\"name\":\"description\"},{\"name\":\"ownerId\"},{\"name\":\"id\"}],\"searchFields\":[]}}\n\nevent: activity.started\ndata: {\"id\":3,\"type\":\"agenticReasoning\",\"startedAt\":\"2025-01-01T00:08:45.045Z\"}\n\nevent: activity.completed\ndata: {\"type\":\"agenticReasoning\",\"id\":3,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"reasoningTokens\":74}\n\nevent: activity.started\ndata: {\"id\":4,\"type\":\"modelAnswerSynthesis\",\"startedAt\":\"2025-01-01T00:08:45.045Z\"}\n\nevent: activity.completed\ndata: {\"type\":\"modelAnswerSynthesis\",\"id\":4,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"inputTokens\":11,\"outputTokens\":22,\"elapsedMs\":1234}\n\nevent: answer.completed\ndata: {\"messageIndex\":0,\"message\":{\"content\":[{\"type\":\"text\",\"text\":\"[{...}]\"}]}}\n\nevent: references.completed\ndata: [{\"type\":\"searchIndex\",\"id\":\"83dd7d40\",\"activitySource\":1,\"rerankerScore\":3.5,\"docKey\":\"myDocKey1\",\"citationUrl\":\"https://typespecstableexampleservice.search.windows.net/indexes/stable-test/docs/myDocKey1?$select=category%2Cdescription%2CownerId%2Cid&api-version=2026-10-01&allowUnsafeKeys=true\",\"sourceData\":{\"id\":\"myDocKey1\",\"title\":\"high_doc\",\"content\":\"hello world\"}},{\"type\":\"searchIndex\",\"id\":\"83dd7d41\",\"activitySource\":1,\"rerankerScore\":2.7,\"docKey\":\"myDocKey2\",\"citationUrl\":\"https://typespecstableexampleservice.search.windows.net/indexes/stable-test/docs/myDocKey2?$select=category%2Cdescription%2CownerId%2Cid&api-version=2026-10-01&allowUnsafeKeys=true\",\"sourceData\":{\"id\":\"myDocKey2\",\"title\":\"low_doc\",\"content\":\"goodbye world\"}}]\n\nevent: response.completed\ndata: {\"statusCode\":200,\"response\":{\"response\":[{\"content\":[{\"type\":\"text\",\"text\":\"[{...}]\"}]}],\"activity\":[{\"type\":\"modelQueryPlanning\",\"id\":0,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"inputTokens\":11,\"outputTokens\":22,\"elapsedMs\":1234},{\"type\":\"searchIndex\",\"id\":1,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"knowledgeSourceName\":\"ks-stable-test\",\"queryTime\":\"2025-01-01T00:08:45.045Z\",\"count\":2,\"elapsedMs\":1234,\"searchIndexArguments\":{\"search\":\"hello world\",\"filter\":\"(category eq 'news') and (foo eq bar)\",\"semanticConfigurationName\":\"testconfig\",\"sourceDataFields\":[{\"name\":\"category\"},{\"name\":\"description\"},{\"name\":\"ownerId\"},{\"name\":\"id\"}],\"searchFields\":[]}},{\"type\":\"searchIndex\",\"id\":2,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"knowledgeSourceName\":\"ks-stable-test\",\"queryTime\":\"2025-01-01T00:08:45.045Z\",\"count\":2,\"elapsedMs\":1234,\"searchIndexArguments\":{\"search\":\"hello world two\",\"filter\":\"(category eq 'news') and (foo eq bar)\",\"semanticConfigurationName\":\"testconfig\",\"sourceDataFields\":[{\"name\":\"category\"},{\"name\":\"description\"},{\"name\":\"ownerId\"},{\"name\":\"id\"}],\"searchFields\":[]}},{\"type\":\"agenticReasoning\",\"id\":3,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"reasoningTokens\":74},{\"type\":\"modelAnswerSynthesis\",\"id\":4,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"inputTokens\":11,\"outputTokens\":22,\"elapsedMs\":1234}],\"references\":[{\"type\":\"searchIndex\",\"id\":\"83dd7d40\",\"activitySource\":1,\"rerankerScore\":3.5,\"docKey\":\"myDocKey1\",\"citationUrl\":\"https://typespecstableexampleservice.search.windows.net/indexes/stable-test/docs/myDocKey1?$select=category%2Cdescription%2CownerId%2Cid&api-version=2026-10-01&allowUnsafeKeys=true\",\"sourceData\":{\"id\":\"myDocKey1\",\"title\":\"high_doc\",\"content\":\"hello world\"}},{\"type\":\"searchIndex\",\"id\":\"83dd7d41\",\"activitySource\":1,\"rerankerScore\":2.7,\"docKey\":\"myDocKey2\",\"citationUrl\":\"https://typespecstableexampleservice.search.windows.net/indexes/stable-test/docs/myDocKey2?$select=category%2Cdescription%2CownerId%2Cid&api-version=2026-10-01&allowUnsafeKeys=true\",\"sourceData\":{\"id\":\"myDocKey2\",\"title\":\"low_doc\",\"content\":\"goodbye world\"}}]}}\n\n"

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.).

FileKnowledgeSourceParams

Specifies runtime parameters for a File knowledge source

IndexedOneLakeKnowledgeSourceParams

Specifies runtime parameters for a indexed OneLake knowledge source

IndexedSharePointKnowledgeSourceParams

Specifies runtime parameters for a indexed SharePoint knowledge source

IndexedSqlKnowledgeSourceParams

Specifies runtime parameters for an indexed SQL knowledge source

KnowledgeBaseImageContent

Image content.

KnowledgeBaseMessage

The natural language message style object.

KnowledgeBaseMessageContentType

The type of message content.

KnowledgeBaseMessageImageContent

Image message type.

KnowledgeBaseMessageTextContent

Text message type.

KnowledgeBaseRetrievalRequest

The input contract for the retrieval request.

KnowledgeRetrievalIntentType

The kind of knowledge base configuration to use.

KnowledgeRetrievalLowReasoningEffort

Run knowledge retrieval with low reasoning effort.

KnowledgeRetrievalMediumReasoningEffort

Run knowledge retrieval with medium reasoning effort.

KnowledgeRetrievalMinimalReasoningEffort

Run knowledge retrieval with minimal reasoning effort.

KnowledgeRetrievalOutputMode

The output configuration for this retrieval.

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

The Accept header.

Value Description
text/event-stream

AzureBlobKnowledgeSourceParams

Specifies runtime parameters for a azure blob knowledge source

Name Type Description
alwaysQuerySource

boolean

Indicates that this knowledge source should bypass source selection and always be queried at retrieval time.

failOnError

boolean

Indicates that the entire retrieval request should fail if retrieval from this knowledge source encounters an error. Defaults to false.

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.

maxOutputDocuments

integer (int32)

Limits the maximum number of documents returned from this knowledge source.

rerankerThreshold

number (float)

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

ErrorAdditionalInfo

The resource management error additional info.

Name Type Description
info

searchservice.knowledgeretrieval.retrievestream

The additional info.

type

string

The additional info type.

ErrorDetail

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

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.

FileKnowledgeSourceParams

Specifies runtime parameters for a File knowledge source

Name Type Description
alwaysQuerySource

boolean

Indicates that this knowledge source should bypass source selection and always be queried at retrieval time.

failOnError

boolean

Indicates that the entire retrieval request should fail if retrieval from this knowledge source encounters an error. Defaults to false.

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:

file

The type of the knowledge source.

knowledgeSourceName

string

The name of the index the params apply to.

maxOutputDocuments

integer (int32)

Limits the maximum number of documents returned from this knowledge source.

rerankerThreshold

number (float)

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

IndexedOneLakeKnowledgeSourceParams

Specifies runtime parameters for a indexed OneLake knowledge source

Name Type Description
alwaysQuerySource

boolean

Indicates that this knowledge source should bypass source selection and always be queried at retrieval time.

failOnError

boolean

Indicates that the entire retrieval request should fail if retrieval from this knowledge source encounters an error. Defaults to false.

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.

maxOutputDocuments

integer (int32)

Limits the maximum number of documents returned from this knowledge source.

rerankerThreshold

number (float)

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

IndexedSharePointKnowledgeSourceParams

Specifies runtime parameters for a indexed SharePoint knowledge source

Name Type Description
alwaysQuerySource

boolean

Indicates that this knowledge source should bypass source selection and always be queried at retrieval time.

failOnError

boolean

Indicates that the entire retrieval request should fail if retrieval from this knowledge source encounters an error. Defaults to false.

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:

indexedSharePoint

The type of the knowledge source.

knowledgeSourceName

string

The name of the index the params apply to.

maxOutputDocuments

integer (int32)

Limits the maximum number of documents returned from this knowledge source.

rerankerThreshold

number (float)

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

IndexedSqlKnowledgeSourceParams

Specifies runtime parameters for an indexed SQL knowledge source

Name Type Description
alwaysQuerySource

boolean

Indicates that this knowledge source should bypass source selection and always be queried at retrieval time.

failOnError

boolean

Indicates that the entire retrieval request should fail if retrieval from this knowledge source encounters an error. Defaults to false.

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:

indexedSql

The type of the knowledge source.

knowledgeSourceName

string

The name of the index the params apply to.

maxOutputDocuments

integer (int32)

Limits the maximum number of documents returned from this knowledge source.

rerankerThreshold

number (float)

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

KnowledgeBaseImageContent

Image content.

Name Type Description
url

string (uri)

The url of the image.

KnowledgeBaseMessage

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

The type of message content.

Value Description
text

Text message content kind.

image

Image message content kind.

KnowledgeBaseMessageImageContent

Image message type.

Name Type Description
image

KnowledgeBaseImageContent

The image content.

type string:

image

The type of the message

KnowledgeBaseMessageTextContent

Text message type.

Name Type Description
text

string

The text content.

type string:

text

The type of the message

KnowledgeBaseRetrievalRequest

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.

maxOutputDocuments

integer (int32)

Limits the maximum number of documents in the output.

maxOutputSizeInTokens

integer (int32)

Limits the maximum size of the content in the output.

maxRuntimeInSeconds

integer (int32)

The maximum runtime in seconds.

messages

KnowledgeBaseMessage[]

A list of chat message style input.

outputMode

KnowledgeRetrievalOutputMode

The output configuration for this retrieval.

retrievalReasoningEffort KnowledgeRetrievalReasoningEffort:

The retrieval reasoning effort configuration.

KnowledgeRetrievalIntentType

The kind of knowledge base configuration to use.

Value Description
semantic

A natural language semantic query intent.

KnowledgeRetrievalLowReasoningEffort

Run knowledge retrieval with low reasoning effort.

Name Type Description
kind string:

low

The kind of reasoning effort.

KnowledgeRetrievalMediumReasoningEffort

Run knowledge retrieval with medium reasoning effort.

Name Type Description
kind string:

medium

The kind of reasoning effort.

KnowledgeRetrievalMinimalReasoningEffort

Run knowledge retrieval with minimal reasoning effort.

Name Type Description
kind string:

minimal

The kind of reasoning effort.

KnowledgeRetrievalOutputMode

The output configuration for this retrieval.

Value Description
extractiveData

Return data from the knowledge sources directly without generative alteration.

answerSynthesis

Synthesize an answer for the response payload.

KnowledgeRetrievalReasoningEffortKind

The amount of effort to use during retrieval.

Value Description
minimal

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

low

Use low reasoning during retrieval.

medium

Use a moderate amount of reasoning during retrieval.

KnowledgeRetrievalSemanticIntent

A semantic query intent.

Name Type Description
search

string

The semantic query to execute

type string:

semantic

The type of the intent.

KnowledgeSourceKind

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.

indexedSharePoint

A knowledge source that reads data from indexed SharePoint.

indexedOneLake

A knowledge source that reads data from indexed OneLake.

indexedSql

A knowledge source that retrieves and ingests data from Azure SQL Database or SQL Managed Instance to a Search Index.

web

A knowledge source that reads data from the web.

file

A knowledge source that supports direct file upload and indexing.

SearchIndexKnowledgeSourceParams

Specifies runtime parameters for a search index knowledge source

Name Type Description
alwaysQuerySource

boolean

Indicates that this knowledge source should bypass source selection and always be queried at retrieval time.

failOnError

boolean

Indicates that the entire retrieval request should fail if retrieval from this knowledge source encounters an error. Defaults to false.

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.

maxOutputDocuments

integer (int32)

Limits the maximum number of documents returned from this knowledge source.

rerankerThreshold

number (float)

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

WebKnowledgeSourceParams

Specifies runtime parameters for a web knowledge source

Name Type Description
alwaysQuerySource

boolean

Indicates that this knowledge source should bypass source selection and always be queried at retrieval time.

count

integer (int32)

The number of web results to return.

failOnError

boolean

Indicates that the entire retrieval request should fail if retrieval from this knowledge source encounters an error. Defaults to false.

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.

maxOutputDocuments

integer (int32)

Limits the maximum number of documents returned from this knowledge source.

rerankerThreshold

number (float)

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