Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Important
APIs under the /beta version are subject to change. Use of these APIs in production applications is not supported.
The Microsoft 365 Copilot Retrieval API allows for the retrieval of relevant text extracts from SharePoint, OneDrive, and Copilot connectors content that the calling user has access to, while respecting the defined access controls within the tenant. Use the Retrieval API to ground your generative AI solutions with Microsoft 365 data while optimizing for context recall.
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
| Permission type | Least privileged permissions | Higher privileged permissions |
|---|---|---|
| Delegated (work or school account) | Files.Read.All, Sites.Read.All* | ExternalItem.Read.All |
| Delegated (personal Microsoft account) | Not supported. | Not supported. |
| Application | Not supported. | Not supported. |
* You need both Files.Read.All and Sites.Read.All permissions to retrieve SharePoint and OneDrive content.
HTTP request
POST https://graph.microsoft.com/beta/copilot/retrieval
POST https://graph.microsoft.com/v1.0/copilot/retrieval
Request headers
| Name | Description |
|---|---|
Authorization |
Bearer {token}. Required. Learn more about authentication and authorization. |
Content-Type |
application/json. Required. |
Request body
In the request body, supply a JSON representation of the parameters.
The following table lists the optional and required parameters that you can use when you call this action.
| Parameter | Type | Description |
|---|---|---|
queryString |
String | Natural language query string used to retrieve relevant text extracts. This parameter has a limit of 1,500 characters. Your queryString should be a single sentence, and you should avoid spelling errors in context-rich keywords. Required. |
dataSource |
String | Indicates whether extracts should be retrieved from SharePoint, OneDrive, or Copilot connectors. Acceptable values are sharePoint, oneDriveBusiness, and externalItem. Required. |
dataSourceConfiguration |
dataSourceConfiguration | Contains additional configuration information for applicable data sources. dataSourceConfiguration includes an object called externalItem, where you can configure Copilot connectors retrieval. Optional. |
filterExpression |
String | Keyword Query Language (KQL) expression with queryable SharePoint, OneDrive, or Copilot connectors properties and attributes to scope the retrieval before the query runs. You can use AND, OR, NOT, and inequality operators where applicable when constructing your filterExpression. Supported SharePoint and OneDrive properties for filtering are: Author, FileExtension, Filename, FileType, InformationProtectionLabelId, LastModifiedTime, ModifiedBy, Path, SiteID, and Title. When filtering on Copilot connectors content, you can use any property marked as queryable in the Copilot connector schema. If you are not familiar with the schema of your desired Copilot connector, or you do not know which properties are marked queryable, reach out to the admin or developer who configured your desired Copilot connector. Microsoft will not resolve any issues with filtering on SharePoint and Copilot connectors properties not mentioned here. You can use multiple properties and operators when constructing your filterExpression. By default, no scoping is applied. Ensure that this parameter has correct KQL syntax before calling the API. Otherwise, the query executes as if there is no filterExpression. Optional. For best practices for filtered queries, see Best practices. |
resourceMetadata |
String collection | A list of metadata fields to be returned for each item in the response. Only retrievable metadata properties can be included in this list. By default, no metadata is returned. Optional. |
maximumNumberOfResults |
Int32 | The number of results that are returned in the response. Must be between 1 and 25. By default, returns up to 25 results. Optional. |
Response
If successful, this action returns a 200 OK response code and a retrievalResponse in the response body.
Examples
Example 1: Retrieve data from SharePoint
The following example shows a request to retrieve data from SharePoint. The request asks for the title and author metadata to be returned for each item from which a text extract is retrieved. The response includes a maximum of 10 documents.
Request
The following example shows the request.
POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "sharePoint",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "10"
}
POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "sharePoint",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "10"
}
Response
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"retrievalHits": [
{
"webUrl": "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx",
"extracts": [
{
"text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
"relevanceScore": 0.8374363553387588
},
{
"text": "You will need to sign in with 2FA to access the corporate VPN.",
"relevanceScore": 0.7465472642498679
}
],
"resourceType": "listItem",
"resourceMetadata": {
"title": "VPN Access",
"author": "John Doe"
},
"sensitivityLabel": {
"sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
"displayName": "Confidential\\Any User (No Protection)",
"toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
"priority": 4,
"color": "#FF8C00"
}
},
{
"webUrl": "https://contoso.sharepoint.com/sites/HR/Corporate_VPN.docx",
"extracts": [
{
"text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
"relevanceScore": 0.7588038775683956
},
{
"text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
"relevanceScore": 0.6696818957446697
}
],
"resourceType": "listItem",
"resourceMetadata": {
"title": "Corporate VPN",
"author": "Jane Doe"
},
"sensitivityLabel": {
"sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
"displayName": "Confidential\\Any User (No Protection)",
"toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
"priority": 4,
"color": "#FF8C00"
}
}
]
}
Example 2: Retrieve data from Copilot connectors
The following example shows a request to retrieve data from Copilot connectors. The request asks for the title and author metadata to be returned for each item from which a text extract is retrieved. The response includes a maximum of 10 documents.
Request
The following example shows the request.
POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "externalItem",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "10"
}
POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "externalItem",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "10"
}
Response
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"retrievalHits": [
{
"webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
"extracts": [
{
"text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
"relevanceScore": 0.874
},
{
"text": "You will need to sign in with 2FA to access the corporate VPN.",
"relevanceScore": 0.801
}
],
"resourceType": "externalItem",
"resourceMetadata": {
"title": "VPN Access",
"author": "John Doe"
}
},
{
"webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
"extracts": [
{
"text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
},
{
"text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
"relevanceScore": 0.655
}
],
"resourceType": "externalItem",
"resourceMetadata": {
"title": "Corporate VPN"
}
}
]
}
Example 3: Batch requests to the Retrieval API
The following example shows how to batch requests to the Retrieval API. The Retrieval API supports up to 20 requests per batch. id in the request payload must be a String that uniquely identifies each request in the batch.
Request
The following example shows the request.
POST https://graph.microsoft.com/beta/$batch
Accept: application/json
Content-Type: application/json
{
"requests": [
{
"id": "1",
"method": "POST",
"url": "/copilot/retrieval",
"body": {
"queryString": "How to setup corporate VPN?",
"dataSource": "sharePoint"
},
"headers": {
"Content-Type": "application/json"
}
},
{
"id": "2",
"method": "POST",
"url": "/copilot/retrieval",
"body": {
"queryString": "How to setup corporate VPN?",
"dataSource": "externalItem"
},
"headers": {
"Content-Type": "application/json"
}
}
]
}
POST https://graph.microsoft.com/v1.0/$batch
Accept: application/json
Content-Type: application/json
{
"requests": [
{
"id": "1",
"method": "POST",
"url": "/copilot/retrieval",
"body": {
"queryString": "How to setup corporate VPN?",
"dataSource": "sharePoint"
},
"headers": {
"Content-Type": "application/json"
}
},
{
"id": "2",
"method": "POST",
"url": "/copilot/retrieval",
"body": {
"queryString": "How to setup corporate VPN?",
"dataSource": "externalItem"
},
"headers": {
"Content-Type": "application/json"
}
}
]
}
Response
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"responses": [
{
"id": "1",
"status": 200,
"headers": {
"Content-Type": "application/json; charset=utf-8"
},
"body": {
"retrievalHits": [
{
"webUrl": "https://contoso.sharepoint.com/sites/HR/VPNAccess.docx",
"extracts": [
{
"text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
"relevanceScore": 0.8374363553387588
},
{
"text": "You will need to sign in with 2FA to access the corporate VPN.",
"relevanceScore": 0.7465472642498679
}
],
"resourceType": "listItem",
"resourceMetadata": {},
"sensitivityLabel": {
"sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
"displayName": "Confidential\\Any User (No Protection)",
"toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
"priority": 4,
"color": "#FF8C00"
}
},
{
"webUrl": "https://contoso.sharepoint.com/sites/HR/Corporate_VPN.docx",
"extracts": [
{
"text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
"relevanceScore": 0.7588038775683956
},
{
"text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
"relevanceScore": 0.6696818957446697
}
],
"resourceType": "listItem",
"resourceMetadata": {},
"sensitivityLabel": {
"sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
"displayName": "Confidential\\Any User (No Protection)",
"toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
"priority": 4,
"color": "#FF8C00"
}
}
]
}
},
{
"id": "2",
"status": 200,
"headers": {
"Content-Type": "application/json; charset=utf-8"
},
"body": {
"retrievalHits": [
{
"webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
"extracts": [
{
"text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
"relevanceScore": 0.874
},
{
"text": "You will need to sign in with 2FA to access the corporate VPN.",
"relevanceScore": 0.801
}
],
"resourceType": "externalItem",
"resourceMetadata": {}
},
{
"webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
"extracts": [
{
"text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
"relevanceScore": 0.772
},
{
"text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
"relevanceScore": 0.655
}
],
"resourceType": "externalItem",
"resourceMetadata": {}
}
]
}
}
]
}
Example 4: Retrieve data from a specific SharePoint site
The following example shows a request to retrieve data from a specific Sharepoint site. The filterExpression parameter specifies the path to the site. The request asks for the title and author metadata to be returned for each item from which a text extract is retrieved. The response should include a maximum of four documents.
Request
The following example shows the request.
POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "sharePoint",
"filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\"",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "4"
}
POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "sharePoint",
"filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\"",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "4"
}
Response
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"retrievalHits": [
{
"webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
"extracts": [
{
"text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
"relevanceScore": 0.8374363553387588
},
{
"text": "You will need to sign in with 2FA to access the corporate VPN.",
"relevanceScore": 0.7465472642498679
}
],
"resourceType": "listItem",
"resourceMetadata": {
"title": "VPN Access",
"author": "John Doe"
},
"sensitivityLabel": {
"sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
"displayName": "Confidential\\Any User (No Protection)",
"toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
"priority": 4,
"color": "#FF8C00"
}
},
{
"webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
"extracts": [
{
"text": "Have your VPN username and password ready prior to starting the configuration.",
"relevanceScore": 0.6465472642498679
},
{
"text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources.",
"relevanceScore": 0.7374363553387588
}
],
"resourceType": "listItem",
"resourceMetadata": {
"title": "VPN Instructions",
"author": "Elisa Mueller"
},
"sensitivityLabel": {
"sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
"displayName": "Confidential\\Any User (No Protection)",
"toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
"priority": 4,
"color": "#FF8C00"
}
}
]
}
Example 5: Retrieve data from multiple SharePoint sites
The following example shows a request to retrieve data from multiple Sharepoint sites. The filterExpression parameter specifies the paths to the sites. The request asks for the title and author metadata to be returned for each item from which a text extract is retrieved. The response should include a maximum of four documents.
Request
The following example shows the request.
POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "sharePoint",
"filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\" OR path:\"https://contoso.sharepoint.com/sites/HR2\"",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "4"
}
POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "sharePoint",
"filterExpression": "path:\"https://contoso.sharepoint.com/sites/HR1/\" OR path:\"https://contoso.sharepoint.com/sites/HR2\"",
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "4"
}
Response
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"retrievalHits": [
{
"webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNAccess.docx",
"extracts": [
{
"text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
"relevanceScore": 0.8374363553387588
},
{
"text": "You will need to sign in with 2FA to access the corporate VPN.",
"relevanceScore": 0.7465472642498679
}
],
"resourceType": "listItem",
"resourceMetadata": {
"title": "VPN Access",
"author": "John Doe"
},
"sensitivityLabel": {
"sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
"displayName": "Confidential\\Any User (No Protection)",
"toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
"priority": 4,
"color": "#FF8C00"
}
},
{
"webUrl": "https://contoso.sharepoint.com/sites/HR2/VPNConfig.docx",
"extracts": [
{
"text": "Have your VPN username and password ready prior to starting the configuration.",
"relevanceScore": 0.6465472642498679
}
],
"resourceType": "listItem",
"resourceMetadata": {
"title": "VPN Config",
"author": "Elisa Mueller"
},
"sensitivityLabel": {
"sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
"displayName": "Confidential\\Any User (No Protection)",
"toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
"priority": 4,
"color": "#FF8C00"
}
},
{
"webUrl": "https://contoso.sharepoint.com/sites/HR1/VPNInstructions.docx",
"extracts": [
{
"text": "Have your VPN username and password ready prior to starting the configuration.",
"relevanceScore": 0.6465472642498679
},
{
"text": "There are multiple VPN options available. Make sure to select the option that grants you access to your desired resources.",
"relevanceScore": 0.7374363553387588
}
],
"resourceType": "listItem",
"resourceMetadata": {
"title": "VPN Instructions",
"author": "Elisa Mueller"
},
"sensitivityLabel": {
"sensitivityLabelId": "f0ddcc93-d3c0-4993-b5cc-76b0a283e252",
"displayName": "Confidential\\Any User (No Protection)",
"toolTip": "Data is classified as Confidential but is NOT PROTECTED to allow access by approved NDA business partners. If a higher level of protection is needed, please use the Sensitivity button on the tool bar to change the protection level.",
"priority": 4,
"color": "#FF8C00"
}
}
]
}
Example 6: Retrieve data from Copilot connectors using specific connection IDs
The following example shows a request that restricts Copilot connectors retrieval to specific connection IDs. The request asks for the title and author metadata to be returned for each item from which a text extract is retrieved. The response includes a maximum of 10 documents.
Request
The following example shows the request.
POST https://graph.microsoft.com/beta/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "externalItem",
"dataSourceConfiguration": {
"externalItem": {
"connections": [
{
"connectionId": "ContosoITServiceNowKB"
},
{
"connectionId": "ContosoHRServiceNowKB"
}
]
}
},
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "10"
}
POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json
{
"queryString": "How to setup corporate VPN?",
"dataSource": "externalItem",
"dataSourceConfiguration": {
"externalItem": {
"connections": [
{
"connectionId": "ContosoITServiceNowKB"
},
{
"connectionId": "ContosoHRServiceNowKB"
}
]
}
},
"resourceMetadata": [
"title",
"author"
],
"maximumNumberOfResults": "10"
}
Response
The following example shows the response.
HTTP/1.1 200 OK
Content-Type: application/json
{
"retrievalHits": [
{
"webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=2gge30c",
"extracts": [
{
"text": "To configure the VPN, click the Wi-Fi icon on your corporate device and select the VPN option.",
"relevanceScore": 0.874
},
{
"text": "You will need to sign in with 2FA to access the corporate VPN.",
"relevanceScore": 0.801
}
],
"resourceType": "externalItem",
"resourceMetadata": {
"title": "VPN Access",
"author": "John Doe"
}
},
{
"webUrl": "https://contoso.service-now.com/sp?id=kb_article&sys_id=b775c03",
"extracts": [
{
"text": "Once you have selected Corporate VPN under the VPN options, log in with your corporate credentials.",
"relevanceScore": 0.772
},
{
"text": "Please contact your IT admin if you are continuing to struggle with accessing the VPN.",
"relevanceScore": 0.655
}
],
"resourceType": "externalItem",
"resourceMetadata": {
"title": "Corporate VPN"
}
}
]
}
Example 7: Use filter expressions
The following are examples of KQL expressions that can be used in the filterExpression property for specific scenarios.
Filter on Copilot connector properties
In this example, Label_Title is a queryable property in the ServiceNow Copilot connector schema. The query is filtered on items that contain Corporate VPN in the Label_Title property.
"filterExpression": "Label_Title:\"Corporate VPN\""
Filter SharePoint results on the Author property
In this example, the query is filtered on items with Megan Bowen as the author.
"filterExpression": "Author:\"Megan Bowen\""
Filter SharePoint results on a specific Date Range using the LastModifiedTime property
In this example, the query is filtered on items modified between July 22, 2024 and January 8, 2025.
"filterExpression": "LastModifiedTime >= 2024-07-22 AND LastModifiedTime <= 2025-01-08"
Filter SharePoint results using the FileExtension property
In this example, the query is filtered on files with the .docx, .pdf, or .pptx file extension.
"filterExpression": "FileExtension:\"docx\" OR FileExtension:\"pdf\" OR FileExtension:\"pptx\""
Filter SharePoint results using the Filename property
In this example, the query is filtered on files named Contoso Mission Statement.docx.
"filterExpression": "Filename:\"Contoso Mission Statement.docx\""
Filter SharePoint results using the FileType property
In this example, the query is filtered on PDF files, PowerPoint presentations, and Word documents.
"filterExpression": "FileType:\"pdf\" OR FileType:\"pptx\" OR FileType:\"docx\""
Determine the sensitivity of SharePoint results by filtering using the InformationProtectionLabelId property
In this example, the query is filtered on items with a specific information protection label.
"filterExpression": "InformationProtectionLabelId:\"f0ddcc93-d3c0-4993-b5cc-76b0a283e252\""
Filter SharePoint results using the ModifiedBy property
In this example, the query is filtered on items modified by Adele Vance.
"filterExpression": "ModifiedBy:\"Adele Vance\""
Filter SharePoint results using the SiteID property
In this example, the query is filtered on items from a specific SharePoint site.
"filterExpression": "SiteID:\"e2cf7e40-d689-41de-99ee-a423811a253c\""
Filter SharePoint results using the Title property
In this example, the query is filtered on items with Windows 10 Device in the title.
"filterExpression": "Title:\"Windows 10 Device\""