Running Copilot Retrieval Searches with the Microsoft Graph PowerShell SDK

Copilot Retrieval API Gives Apps Ability to Ground Queries

If your tenant has Microsoft 365 Copilot license or is willing to use a Pay-as-you-go consumption model to fund Copilot services, you might like to play with the Microsoft Graph Copilot retrieval API. The API is designed to return text extracts from content stored SharePoint Online, OneDrive for Business, and Copilot connectors that apps can use to “ground” user prompts before calling a generative AI engine to process the prompts. A Copilot Search API is also available. The difference between the search and retrieval APIs is that the search API runs a semantic search whereas the retrieval API uses a Retrieval Augmented Generation (RAG) search. The results achieved using the two APIs can be quite different.

Grounding against Microsoft 365 content is a major competitive advantage enjoyed by Microsoft 365 Copilot over third-party generative AI solutions. Solutions like ChatGPT enterprise can upload individual documents for processing, but they cannot look for information within Microsoft 365 to help the AI understand the full context of a user request.

Understanding how APIs work gives an insight into how technology functions. Understanding how apps can call Copilot to retrieve information gives insight into how the Copilot integrations with apps like Word, Excel, and PowerPoint work, because the integrated apps all retrieve information through the Graph to ground their queries.

Access Limited to the Signed-In User

Use of the Copilot Retrieval API is free for users with Copilot for Microsoft 365 licenses. In fact, just like Microsoft 365 Copilot, the API only functions within the context of a signed-in user. In Graph terms, this means that the API uses delegated permissions like Files.Read.All and Sites.Read.All (and for connectors, ExternalItem.Read.All) to search for information that’s available to the signed-in user.

Using the Copilot Retrieval API with the Microsoft Graph PowerShell SDK

For the remainder of this article, I use V2.35.1 of the Microsoft Graph PowerShell SDK to communicate with the Copilot Retrieval API in an interactive session. First, sign in with the required permissions:

Connect-MgGraph -NoWelcome -Scopes Files.Read.All, Sites.Read.All

Both permissions are required to let the API read the SharePoint Online and OneDrive sites that the signed-in user can access, and to read the files stored in those locations.

The next step is to populate a variable with the Graph endpoint for the Copilot Retrieval API:

$Uri = 'https://graph.microsoft.com/v1.0/copilot/retrieval'

Now build a hash table containing the request body for a search request. The API supports searches against a limited set of data sources (SharePoint Online, OneDrive for Business, and Copilot connectors or the “ExternalItem” data source). Although Copilot can ground prompts against messages found in Exchange Online and Teams, neither repository is currently an option for the Copilot Retrieval API:

$BodyRequest = @{}
$BodyRequest.Add("datasource", "sharepoint")
$BodyRequest.Add("queryString", "How to write PowerShell for Microsoft 365")
$bodyRequest.Add("maximumNumberOfResults", "3")

The request body contains a filter to improve the accuracy of the search hits returned by the request. The search is against SharePoint, so the filter expression is in KeyQL syntax for SharePoint searches, just like the filters used with Microsoft Search and eDiscovery. This example restricts Copilot to retrieving Word documents between two dates. Remember that Copilot can retrieve all kinds of Office documents and PDFs as well as objects like SharePoint pages, so restricting output based on file type might not be a good idea.

$BodyRequest.add("filterexpression",’FileExtension:"DOCX" AND LastModifiedTime>=2025-11-01 AND LastModifiedTime<=2026-01-31')

Optionally, populate an array containing the names of the metadata properties to retrieve for each search hit and add the array to the request body:

$Metadata = "title", "author", "size", "Created", "LastModifiedTime"

$BodyRequest.add("resourceMetadata", $metadata)

When the request body is complete, issue a POST request to run the retrieval request:

[array]$Data = Invoke-MgGraphRequest -Uri $Uri -Method Post -Body $BodyRequest -OutputType PsObject

Interpreting Copilot Retrieval Hits

After issuing a successful request, the $Data output array should hold an array of RetrievalHits that can be navigated like any other array. This example code outputs the filename, author, created date, relevance score (how relevant the hit is to the query), and the sensitivity label assigned to the file, if one exists. In addition to the metadata, Copilot also retrieves a text extract for files that’s a couple of thousand characters long. The idea is that apps use the information contained in the files found by the API to add context to the query the app sends to the generative AI engine for processing.

The information found by the Copilot Retrieval API can be output with a command like this:

$Hits = $Data.RetrievalHits
ForEach ($Hit in $Hits) {
   Write-Host “File:” $Hit.ResourceMetaData.Title
   Write-Host “Author:” $Hit.ResourceMetaData.Author
   Write-Host “Created:” $Hit.ResourceMetadata.Created
   Write-Host “Relevance:” $Hit.extracts.relevanceScore
   Write-Host “Label:” $Hit.SensitivityLabel.DisplayName
   Write-Host “Extract:” $Hit.extracts.text.substring(0,120)
   Write-Host “-------------------------------------------"
}

The output for a hit created by the code above looks something like this:

File: Using Graph API requests or the Graph PowerShell SDK
Author: Tony Redmond
Created: 30/05/2024 14:57:31
Relevance: 0.7899147536874066 0.8195143018070271 0.8282432736321905
Label: Email Labels\Public
Extract:
## Choosing Between Graph API Requests or Graph SDK Cmdlets

### Which to Choose for PowerShell Development?

I’
## Choosing Between Graph API Requests or Graph SDK Cmdlets

### A Word About Returned Values

When you run a Gr
## Choosing Between Graph API Requests or Graph SDK Cmdlets

### Mix and Match

The important thing to remember
-------------------------------------------

You can download a script that generates slightly nicer output (Figure 1) from the Office 365 for IT Pros GitHub repository.

I spent an interesting few hours playing with the Copilot Retrieval API. I’m not quite sure how I’ll use the knowledge acquired in that time, but you never know when something learned a while ago suddenly becomes important.

---

So much change, all the time. It’s a challenge to stay abreast of all the updates Microsoft makes across the Microsoft 365 ecosystem. Subscribe to the Office 365 for IT Pros eBook to receive insights updated monthly into what happens within Microsoft 365, why it happens, and what new features and capabilities mean for your tenant.