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-11-01-preview

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-query-work-iq-source-authorization

string (password)

User assertion token for a customer-owned Entra app registration configured on a Work IQ knowledge source. Used for on-behalf-of authentication to the Work IQ API.

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.

maxOutputSize

integer (int32)

Limits the maximum size of the content 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.

toolName

string

The tool to select. Omit for KB-wide retrieval.

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://typespecpreviewexampleservice.search.windows.net/knowledgebases('base-preview-test')/retrieve?_overload=retrieveStream&api-version=2026-11-01-preview





{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "hello world"
        }
      ]
    }
  ],
  "maxRuntimeInSeconds": 60,
  "maxOutputSize": 100000,
  "maxOutputDocuments": 50,
  "retrievalReasoningEffort": {
    "kind": "low"
  },
  "includeActivity": true,
  "outputMode": "answerSynthesis",
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "ks-preview-test",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "alwaysQuerySource": false,
      "neverQuerySource": false,
      "failOnError": false,
      "rerankerThreshold": 2.1,
      "resultsProcessing": "rerank",
      "kind": "searchIndex",
      "filterAddOn": "foo eq bar",
      "queryHintOverrides": {
        "filters": [
          {
            "field": "country",
            "fieldValues": [
              "United States",
              "Japan",
              "France",
              "Germany"
            ],
            "filterInstructions": "Country associated with the document."
          }
        ],
        "boosts": [
          {
            "kind": "fieldValue",
            "boostInstructions": "Prefer documents matching the user's locale.",
            "field": "language",
            "fieldValues": [
              "en-US",
              "ja-JP",
              "fr-FR",
              "de-DE"
            ],
            "boost": 1.5
          }
        ]
      },
      "topicGraph": {
        "kind": "diverse",
        "diversityFactor": 0.1
      }
    }
  ],
  "toolName": "product-search"
}

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,\"model\":{\"modelName\":\"gpt-4o\",\"deploymentId\":\"gpt-4o-deployment\"}}\n\nevent: activity.started\ndata: {\"id\":1,\"type\":\"searchIndex\",\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"knowledgeSourceName\":\"ks-preview-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-preview-test\",\"queryTime\":\"2025-01-01T00:08:45.045Z\",\"count\":2,\"elapsedMs\":1234,\"searchIndexArguments\":{\"search\":\"hello world\",\"filter\":\"((category eq 'news') and ((id ne null) and (foo eq bar))) and (Key eq 'myDocKey1')\",\"semanticConfigurationName\":\"testconfig\",\"queryType\":\"simple\",\"sourceDataFields\":[{\"name\":\"category\"},{\"name\":\"description\"},{\"name\":\"ownerId\"},{\"name\":\"id\"}],\"searchFields\":[]},\"queryHintProcessing\":{\"generatedFilter\":\"Key eq 'myDocKey1'\"}}\n\nevent: activity.started\ndata: {\"id\":2,\"type\":\"searchIndex\",\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"knowledgeSourceName\":\"ks-preview-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-preview-test\",\"queryTime\":\"2025-01-01T00:08:45.045Z\",\"count\":2,\"elapsedMs\":1234,\"searchIndexArguments\":{\"search\":\"hello world two\",\"filter\":\"((category eq 'news') and ((id ne null) and (foo eq bar))) and (Key eq 'myDocKey1')\",\"semanticConfigurationName\":\"testconfig\",\"queryType\":\"simple\",\"sourceDataFields\":[{\"name\":\"category\"},{\"name\":\"description\"},{\"name\":\"ownerId\"},{\"name\":\"id\"}],\"searchFields\":[]},\"queryHintProcessing\":{\"generatedFilter\":\"Key eq 'myDocKey1'\"}}\n\nevent: activity.started\ndata: {\"id\":3,\"type\":\"modelAnswerSynthesis\",\"startedAt\":\"2025-01-01T00:08:45.045Z\"}\n\nevent: activity.completed\ndata: {\"type\":\"modelAnswerSynthesis\",\"id\":3,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"inputTokens\":11,\"outputTokens\":22,\"elapsedMs\":1234,\"model\":{\"modelName\":\"gpt-4o\",\"deploymentId\":\"gpt-4o-deployment\"}}\n\nevent: activity.started\ndata: {\"id\":4,\"type\":\"agenticReasoning\",\"startedAt\":\"2025-01-01T00:08:45.045Z\"}\n\nevent: activity.completed\ndata: {\"type\":\"agenticReasoning\",\"id\":4,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"reasoningTokens\":78,\"retrievalReasoningEffort\":{\"kind\":\"low\"},\"logicalReasoningEffort\":{\"kind\":\"low\"}}\n\nevent: answer.completed\ndata: {\"messageIndex\":0,\"message\":{\"content\":[{\"type\":\"text\",\"text\":\"[{...}]\"}]}}\n\nevent: references.completed\ndata: [{\"type\":\"searchIndex\",\"id\":\"83dd7d40\",\"activitySource\":1,\"rerankerScore\":4,\"docKey\":\"myDocKey1\",\"citationUrl\":\"https://typespecpreviewexampleservice.search.windows.net/indexes/preview-test/docs/myDocKey1?$select=category%2Cdescription%2CownerId%2Cid&api-version=2026-11-01-preview&allowUnsafeKeys=true\",\"sourceData\":{\"id\":\"myDocKey1\",\"title\":\"high_doc\",\"content\":\"hello world\"}},{\"type\":\"searchIndex\",\"id\":\"83dd7d41\",\"activitySource\":1,\"rerankerScore\":3.9,\"docKey\":\"myDocKey2\",\"citationUrl\":\"https://typespecpreviewexampleservice.search.windows.net/indexes/preview-test/docs/myDocKey2?$select=category%2Cdescription%2CownerId%2Cid&api-version=2026-11-01-preview&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,\"model\":{\"modelName\":\"gpt-4o\",\"deploymentId\":\"gpt-4o-deployment\"}},{\"type\":\"searchIndex\",\"id\":1,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"knowledgeSourceName\":\"ks-preview-test\",\"queryTime\":\"2025-01-01T00:08:45.045Z\",\"count\":2,\"elapsedMs\":1234,\"searchIndexArguments\":{\"search\":\"hello world\",\"filter\":\"((category eq 'news') and ((id ne null) and (foo eq bar))) and (Key eq 'myDocKey1')\",\"semanticConfigurationName\":\"testconfig\",\"queryType\":\"simple\",\"sourceDataFields\":[{\"name\":\"category\"},{\"name\":\"description\"},{\"name\":\"ownerId\"},{\"name\":\"id\"}],\"searchFields\":[]},\"queryHintProcessing\":{\"generatedFilter\":\"Key eq 'myDocKey1'\"}},{\"type\":\"searchIndex\",\"id\":2,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"knowledgeSourceName\":\"ks-preview-test\",\"queryTime\":\"2025-01-01T00:08:45.045Z\",\"count\":2,\"elapsedMs\":1234,\"searchIndexArguments\":{\"search\":\"hello world two\",\"filter\":\"((category eq 'news') and ((id ne null) and (foo eq bar))) and (Key eq 'myDocKey1')\",\"semanticConfigurationName\":\"testconfig\",\"queryType\":\"simple\",\"sourceDataFields\":[{\"name\":\"category\"},{\"name\":\"description\"},{\"name\":\"ownerId\"},{\"name\":\"id\"}],\"searchFields\":[]},\"queryHintProcessing\":{\"generatedFilter\":\"Key eq 'myDocKey1'\"}},{\"type\":\"modelAnswerSynthesis\",\"id\":3,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"inputTokens\":11,\"outputTokens\":22,\"elapsedMs\":1234,\"model\":{\"modelName\":\"gpt-4o\",\"deploymentId\":\"gpt-4o-deployment\"}},{\"type\":\"agenticReasoning\",\"id\":4,\"startedAt\":\"2025-01-01T00:08:45.045Z\",\"completedAt\":\"2025-01-01T00:08:46.279Z\",\"reasoningTokens\":78,\"retrievalReasoningEffort\":{\"kind\":\"low\"},\"logicalReasoningEffort\":{\"kind\":\"low\"}}],\"references\":[{\"type\":\"searchIndex\",\"id\":\"83dd7d40\",\"activitySource\":1,\"rerankerScore\":4,\"docKey\":\"myDocKey1\",\"citationUrl\":\"https://typespecpreviewexampleservice.search.windows.net/indexes/preview-test/docs/myDocKey1?$select=category%2Cdescription%2CownerId%2Cid&api-version=2026-11-01-preview&allowUnsafeKeys=true\",\"sourceData\":{\"id\":\"myDocKey1\",\"title\":\"high_doc\",\"content\":\"hello world\"}},{\"type\":\"searchIndex\",\"id\":\"83dd7d41\",\"activitySource\":1,\"rerankerScore\":3.9,\"docKey\":\"myDocKey2\",\"citationUrl\":\"https://typespecpreviewexampleservice.search.windows.net/indexes/preview-test/docs/myDocKey2?$select=category%2Cdescription%2CownerId%2Cid&api-version=2026-11-01-preview&allowUnsafeKeys=true\",\"sourceData\":{\"id\":\"myDocKey2\",\"title\":\"low_doc\",\"content\":\"goodbye world\"}}]}}\n\n"

Definitions

Name Description
Accept

The Accept header.

AgentRuntimeGraphHydrateDocumentsParams

Selection and count limits for hydrated source documents returned by knowledge retrieval.

AgentRuntimeGraphParams

Graph-specific overrides for a graph-enabled Azure Blob knowledge source during retrieval.

AgentRuntimeGraphProvenanceParams

Source-document hydration policy for knowledge retrieval graph results.

AzureBlobKnowledgeSourceParams

Specifies runtime parameters for a azure blob knowledge source

BalancedVectorQueryTopicGraph

Blends pure vector similarity with diversity-aware retrieval. Recommended default to balance diversity with relevance.

DiverseVectorQueryTopicGraph

Uses topic graph diverse retrieval.

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

FabricDataAgentKnowledgeSourceParams

Specifies runtime parameters for a Fabric Data Agent knowledge source

FabricOntologyKnowledgeSourceParams

Specifies runtime parameters for a Fabric Ontology knowledge source

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.

KnowledgeRetrievalAutoReasoningEffort

Automatically select the reasoning effort during retrieval. The service seeds every request at the cheapest tier and escalates only as far as needed, up to the service's maximum available tier.

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.

KnowledgeSourceGraphProvenanceKind

Source-document behavior for graph-based knowledge retrieval.

KnowledgeSourceKind

The kind of the knowledge source.

KnowledgeSourceResultsProcessing

Controls whether a knowledge source's results are reranked.

McpServerKnowledgeSourceParams

Specifies runtime parameters for an MCP server knowledge source

NoneVectorQueryTopicGraph

Uses normal vector search without topic graph diverse retrieval.

RemoteSharePointKnowledgeSourceParams

Specifies runtime parameters for a remote SharePoint knowledge source

SearchIndexKnowledgeSourceBoostKind

The kind of boost hint for a search index knowledge source.

SearchIndexKnowledgeSourceFieldValueBoost

A hint that boosts documents based on a field value.

SearchIndexKnowledgeSourceFilterHint

A hint that identifies a field and exhaustive grounding values the query planner can use when constructing a filter.

SearchIndexKnowledgeSourceFilterHintAutoConfiguration

Configures automatic resolution of a filter hint's grounding values from the target index facets.

SearchIndexKnowledgeSourceMultiWordExpressionBoost

A hint that boosts documents based on a multi-word expression.

SearchIndexKnowledgeSourceParams

Specifies runtime parameters for a search index knowledge source

SearchIndexKnowledgeSourceQueryHints

Hints that guide query planning toward useful filters and boosts for a search index knowledge source.

VectorSearchTopicGraphKind

The kind of topic graph vector search to use.

WebKnowledgeSourceParams

Specifies runtime parameters for a web knowledge source

WorkIQKnowledgeSourceParams

Specifies runtime parameters for a WorkIQ knowledge source

Accept

The Accept header.

Value Description
text/event-stream

AgentRuntimeGraphHydrateDocumentsParams

Selection and count limits for hydrated source documents returned by knowledge retrieval.

Name Type Default value Description
select

string

Comma-separated retrievable source fields to include.

top

integer (int32)

minimum: 1
maximum: 100
50

Maximum hydrated documents to return. Defaults to 50; this is independent of graph-row count.

AgentRuntimeGraphParams

Graph-specific overrides for a graph-enabled Azure Blob knowledge source during retrieval.

Name Type Default value Description
includeQuery

boolean

False

Include generated GQL in graphSearchArguments.gql. Omitted or false does not expose generated query text.

provenance

AgentRuntimeGraphProvenanceParams

Controls whether source documents supporting graph results are also returned.

AgentRuntimeGraphProvenanceParams

Source-document hydration policy for knowledge retrieval graph results.

Name Type Default value Description
hydrateDocuments

AgentRuntimeGraphHydrateDocumentsParams

Source-document options; only valid when kind is hydrate.

kind

KnowledgeSourceGraphProvenanceKind

none

Whether graph retrieval returns graph rows only or also hydrates source documents.

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.

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

failOnError

boolean

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

graphParameters

AgentRuntimeGraphParams

Graph-query visibility and source-document hydration options for a graph-enabled source.

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

topicGraph VectorQueryTopicGraph:

Overrides the knowledge source's stored topicGraph for this retrieval. When omitted, the stored knowledge source value applies.

BalancedVectorQueryTopicGraph

Blends pure vector similarity with diversity-aware retrieval. Recommended default to balance diversity with relevance.

Name Type Description
kind string:

balanced

The kind of topic graph vector search to use.

minDiversityPoolSize

integer (int32)

minimum: 250
maximum: 10000

The minimum number of vector candidates to retrieve before topic graph sampling. The default is 1,000.

DiverseVectorQueryTopicGraph

Uses topic graph diverse retrieval.

Name Type Description
diversityFactor

number (float)

minimum: 0
maximum: 1

The diversity factor used for topic graph diverse retrieval. If omitted, the default configured on the topic graph profile is used.

kind string:

diverse

The kind of topic graph vector search to use.

minDiversityPoolSize

integer (int32)

minimum: 250
maximum: 10000

The minimum number of vector candidates to retrieve before topic graph sampling. The default is 1,000.

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.

FabricDataAgentKnowledgeSourceParams

Specifies runtime parameters for a Fabric Data Agent knowledge source

Name Type Description
alwaysQuerySource

boolean

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

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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:

fabricDataAgent

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

FabricOntologyKnowledgeSourceParams

Specifies runtime parameters for a Fabric Ontology knowledge source

Name Type Description
alwaysQuerySource

boolean

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

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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:

fabricOntology

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

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.

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

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.

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

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.

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

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.

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

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.

maxOutputSize

integer (int32)

Limits the maximum size of the content 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.

toolName

string

The tool to select. Omit for KB-wide retrieval.

KnowledgeRetrievalAutoReasoningEffort

Automatically select the reasoning effort during retrieval. The service seeds every request at the cheapest tier and escalates only as far as needed, up to the service's maximum available tier.

Name Type Description
kind string:

auto

The kind of reasoning effort.

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.

auto

Automatically select the reasoning effort during retrieval, escalating from the cheapest tier only as far as needed.

KnowledgeRetrievalSemanticIntent

A semantic query intent.

Name Type Description
search

string

The semantic query to execute

type string:

semantic

The type of the intent.

KnowledgeSourceGraphProvenanceKind

Source-document behavior for graph-based knowledge retrieval.

Value Description
none

Return graph results without hydrating their source documents.

hydrate

Also return selected source documents from the configured provenance index.

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.

remoteSharePoint

A knowledge source that reads data from remote SharePoint.

workIQ

A knowledge source that reads data from work IQ

file

A knowledge source that supports direct file upload and indexing.

mcpServer

A knowledge source backed by an MCP (Model Context Protocol) server.

fabricDataAgent

A knowledge source that retrieves data from a Fabric Data Agent.

fabricOntology

A knowledge source that retrieves data from Microsoft Fabric Ontology ontologies.

KnowledgeSourceResultsProcessing

Controls whether a knowledge source's results are reranked.

Value Description
rerank

Results from this knowledge source go through the reranking pipeline. This is the default behavior.

none

Results from this knowledge source bypass reranking and preserve their underlying order.

McpServerKnowledgeSourceParams

Specifies runtime parameters for an MCP server knowledge source

Name Type Description
alwaysQuerySource

boolean

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

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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:

mcpServer

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

NoneVectorQueryTopicGraph

Uses normal vector search without topic graph diverse retrieval.

Name Type Description
kind string:

none

The kind of topic graph vector search to use.

RemoteSharePointKnowledgeSourceParams

Specifies runtime parameters for a remote SharePoint knowledge source

Name Type Description
alwaysQuerySource

boolean

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

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

failOnError

boolean

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

filterExpressionAddOn

string

A filter condition applied to the SharePoint data source. It must be specified in the Keyword Query Language syntax. It will be combined as a conjunction with the filter expression specified in the knowledge source definition.

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:

remoteSharePoint

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

SearchIndexKnowledgeSourceBoostKind

The kind of boost hint for a search index knowledge source.

Value Description
fieldValue

Boost documents based on a field value.

multiWordExpression

Boost documents based on a multi-word expression.

SearchIndexKnowledgeSourceFieldValueBoost

A hint that boosts documents based on a field value.

Name Type Description
boost

number (double)

A multiplier for the document score. Must be a positive number not equal to 1.0.

boostInstructions

string

Natural-language instructions that explain when and how to apply the boost.

field

string

minLength: 1

The name of the search index field.

fieldValues

string[]

Representative values for the field.

kind string:

fieldValue

The kind of boost hint.

SearchIndexKnowledgeSourceFilterHint

A hint that identifies a field and exhaustive grounding values the query planner can use when constructing a filter.

Name Type Description
autoConfiguration

SearchIndexKnowledgeSourceFilterHintAutoConfiguration

Configures the service to resolve grounding values from the field's facets. Its presence enables auto-configuration. The field must be filterable and facetable. Not supported when the target index has document-level permissions or Purview sensitivity labels enabled; this restriction is validated at knowledge source create/update and knowledge base retrieval time. Mutually exclusive with fieldValues. Supported only in a knowledge source's stored queryHints, not in request-time queryHintOverrides.

field

string

minLength: 1

The name of the filterable search index field.

fieldValues

string[]

The exhaustive set of values for the field. At most 160 values, with a maximum of 128 characters per value and 2048 characters combined. In versions supporting autoConfiguration, required unless autoConfiguration is specified, and mutually exclusive with it.

filterInstructions

string

Natural-language instructions that explain when and how to filter on the field.

SearchIndexKnowledgeSourceFilterHintAutoConfiguration

Configures automatic resolution of a filter hint's grounding values from the target index facets.

Name Type Description
cacheTtl

integer (int32)

minimum: 60
maximum: 3600

The number of seconds resolved facet values are cached. The allowed range is 60 through 3600 on dedicated services and 60 through 900 on serverless services. When omitted, defaults to 3600 seconds on dedicated services and 900 seconds on serverless services.

maxFacetValueCount

integer (int32)

minimum: 1
maximum: 64

The maximum number of facet values to use as grounding. Defaults to 64; allowed range is 1 through 64. Values are selected in descending facet-count order, subject to the same 2048-character combined-length limit and 128-character per-value limit as manually specified filter values.

SearchIndexKnowledgeSourceMultiWordExpressionBoost

A hint that boosts documents based on a multi-word expression.

Name Type Description
boost

number (double)

A multiplier for the document score. Must be a positive number not equal to 1.0.

boostInstructions

string

Natural-language instructions that explain when and how to apply the boost.

fieldValues

string[]

Representative values for the boost.

kind string:

multiWordExpression

The kind of boost hint.

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.

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

queryHintOverrides

SearchIndexKnowledgeSourceQueryHints

Hints that guide query planning toward useful filters and boosts. If specified, this object replaces the complete set of query hints configured on the knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

topicGraph VectorQueryTopicGraph:

Overrides the knowledge source's stored topicGraph for this retrieval. When omitted, the stored knowledge source value applies.

SearchIndexKnowledgeSourceQueryHints

Hints that guide query planning toward useful filters and boosts for a search index knowledge source.

Name Type Description
boosts SearchIndexKnowledgeSourceBoost[]:

Boost hints that identify conditions the query planner can use to influence document ranking.

filters

SearchIndexKnowledgeSourceFilterHint[]

Filter hints that identify fields and representative values the query planner can use when constructing filters.

VectorSearchTopicGraphKind

The kind of topic graph vector search to use.

Value Description
none

Use normal vector search when topic graph diverse retrieval is off.

diverse

Use topic graph diverse retrieval.

balanced

Blends pure vector similarity with diversity-aware retrieval. Recommended default to balance diversity with relevance.

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.

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.

WorkIQKnowledgeSourceParams

Specifies runtime parameters for a WorkIQ knowledge source

Name Type Description
alwaysQuerySource

boolean

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

enableImageServing

boolean

Indicates whether image serving should be enabled for this knowledge source at retrieval time. When true, images extracted during ingestion are delivered to downstream models.

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:

workIQ

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.

neverQuerySource

boolean

Indicates that this knowledge source should be excluded from the request's candidate set and never queried at retrieval time. The exclusion is request-local and does not modify knowledge base membership. Cannot be combined with alwaysQuerySource on the same knowledge source.

rerankerThreshold

number (float)

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

resultsProcessing

KnowledgeSourceResultsProcessing

Overrides the knowledge source's stored resultsProcessing for this retrieve call only. When omitted, the stored knowledge source value applies.