Die Copilot Retrieval API – Zugriff auf Unternehmenswissen ohne Copilot-Lizenz

Auf sowas hab ich gewartet. Nicht weil ich unbedingt noch eine API lernen wollte, sondern weil RAG auf Basis von Microsoft 365 Daten bisher immer bedeutet hat: entweder volle Copilot-Lizenzen zahlen oder sich seinen eigenen Retrieval-Stack zusammenbauen. Beides war nicht wirklich leiwand.

Microsoft hat begonnen, die Komponenten, die Microsoft 365 Copilot antreiben, als eigenständige APIs verfügbar zu machen. Die erste Welle kam bei der Build 2025 – Retrieval, Interactions Export, Change Notifications, Meeting Insights und Chat. Die Retrieval API ist die, zu der ich immer wieder zurückkomme, weil sie ein Problem löst, das mich schon länger beschäftigt: Wie groundest du deine Custom-AI-Lösungen mit Unternehmenswissen, ohne den gesamten Such- und Indexierungsstack selbst nachzubauen?

Und jetzt kommt der Clou – du kannst sie jetzt ohne Copilot-Add-on-Lizenz verwenden. Pay-as-you-go. Zehn Cent pro API-Aufruf. Das ändert die Kalkulation für viele Custom-App-Szenarien grundlegend.

Was die Retrieval API tatsächlich macht

Ich sag’s direkt: Die Retrieval API gibt dir programmatischen Zugriff auf den gleichen Hybrid-Index, der Microsoft 365 Copilot antreibt. Du schickst eine natürlichsprachige Abfrage hin, und du bekommst relevante Text-Chunks aus SharePoint, OneDrive und Copilot Connectors zurück – permission-trimmed, mit Sensitivity Labels, bereit zum Füttern deines LLM.

Das ist RAG ohne Infrastruktur. Du brauchst keine Vector Database aufsetzen, keine Chunking Pipeline bauen, kein Berechtigungsmodell nachbilden und keine Daten duplizieren. Der Content bleibt wo er ist, die Sicherheit bleibt intakt, und du bekommst die Extracts die du brauchst.

Die API führt unter der Haube Query Transformations durch – die gleichen die Copilot verwendet – und liefert deshalb bessere Ergebnisse als einfache lexikalische Suche oder eine naive RAG-Implementierung, die du dir selbst zusammenbasteln würdest.

Statt dir eine eigene Retrieval Pipeline auf Basis von Microsoft Graph Suchergebnissen zu bauen, nutzt du einfach die, die Microsoft schon für Copilot gebaut hat. Gleiche Engine, gleiche Qualität, deine App.

Pay-as-you-go ohne Copilot-Lizenz

Hier wird es interessant. Bisher hat die Nutzung jeglicher Copilot-Funktionalität eine Microsoft 365 Copilot-Add-on-Lizenz erfordert – rund 30 Dollar pro User pro Monat. Das war ein schwieriger Pitch für Custom Apps, bei denen du nur den Grounding Layer brauchst und nicht das volle Copilot-Erlebnis.

Das Pay-as-you-go Preview ändert das. User ohne Copilot-Lizenz können jetzt die Retrieval API für $0,10 pro API-Aufruf nutzen, abgerechnet über dein Azure-Abonnement. Es gibt eine Voraussetzung, die dich vielleicht stolpern lässt: Dein Tenant braucht nach wie vor mindestens eine Copilot-Lizenz. Aber du brauchst nicht für jeden User, der die API aufruft, eine.

Ein paar Dinge zum Pay-as-you-go-Modell:

• Pay-as-you-go deckt nur Tenant-Level-Quellen ab – SharePoint und Copilot Connectors. OneDrive (User Level) ist ohne volle Copilot-Lizenz nicht verfügbar.
• Das Preview läuft bis 31. Jänner 2027 oder 30 Tage nach GA, je nachdem was zuerst kommt. Kein SLA während des Previews.
• Du aktivierst es im Microsoft 365 Admin Center unter Copilot > Billing & usage > Pay-as-you-go. Rechne mit etwa zwei Stunden für die Propagierung.
• Die Abrechnung läuft über dein Azure-Abonnement als “Pay as you go Copilot Credit” unter der Microsoft Copilot Studio Meter-Kategorie.

Für einen Custom Agent, der vielleicht 50-100 Retrieval-Aufrufe pro User pro Monat macht, schaust du auf 5 bis 10 Dollar statt 30. Wesentlich einfacher zu rechtfertigen als 30 pro Kopf.

Was du damit bauen kannst

Sobald Retrieval von Per-User-Copilot-Lizenzen entkoppelt ist, kannst du Sachen machen, die vorher finanziell keinen Sinn ergeben haben.

Ein HR-Support-Agent zum Beispiel, der Fragen zu Richtlinien beantwortet, indem er Antworten auf SharePoint-gehosteten Policy-Dokumenten grounded. Nur der Agent macht API-Aufrufe, nicht jeder Mitarbeiter. Oder ein Legal-Review-Tool, das relevante Vertragsklauseln aus deiner Dokumentenbibliothek abruft, eingeschränkt auf bestimmte Sites mit KQL-Filtern. Finance-Teams, die Kontext aus Quartalsberichten ziehen. Compliance, die Audit-Antworten in internen Docs grounded.

Du kannst auch SharePoint-Content mit Daten aus Copilot Connectors kombinieren – ServiceNow, Confluence, was auch immer du indexiert hast – in einem einzigen Retrieval-Aufruf. Eine Query, mehrere Quellen über Batch Requests.

Interne Developer Portals sind auch ein guter Anwendungsfall. Ground deine Dokumentationsantworten in deinen tatsächlichen SharePoint-gehosteten Architektur-Docs und Runbooks, statt generische Antworten von einem LLM zu bekommen, das deine Codebase noch nie gesehen hat.

Schritt für Schritt: die Retrieval API aufrufen

Genug Hintergrund. So sieht eine tatsächliche Implementierung aus.

1. App-Registrierung und Berechtigungen

Registrier eine App in Microsoft Entra ID (das App Registrations Blade im Azure Portal). Du brauchst diese Delegated Permissions:

Wichtig: Die Retrieval API unterstützt ausschließlich Delegated Permissions. Application Permissions werden nicht unterstützt. Die API läuft immer im Kontext eines angemeldeten Users, und Ergebnisse werden auf das permission-trimmed, was dieser User sehen darf. Das ist ein Feature, keine Einschränkung – so stellt Microsoft sicher, dass das Sicherheitsmodell hält.

2. Access Token holen

Standard OAuth 2.0 Authorization Code Flow, weil wir Delegated Permissions brauchen. Wenn du MSAL verwendest:

const { ConfidentialClientApplication } = require('@azure/msal-node');

const msalConfig = {
  auth: {
    clientId: '{your-client-id}',
    authority: 'https://login.microsoftonline.com/{tenant-id}',
    clientSecret: '{your-client-secret}'
  }
};

const cca = new ConfidentialClientApplication(msalConfig);

const tokenRequest = {
  scopes: ['https://graph.microsoft.com/Files.Read.All',
           'https://graph.microsoft.com/Sites.Read.All'],
  code: authorizationCode, // from the redirect
  redirectUri: '{your-redirect-uri}'
};

const response = await cca.acquireTokenByCode(tokenRequest);
const accessToken = response.accessToken;

3. Den Retrieval-Aufruf machen

Der Endpoint liegt unter dem Microsoft Graph Namespace. Sowohl v1.0 als auch beta sind verfügbar:

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json
Authorization: Bearer {access-token}

{
  "queryString": "What is our company policy on remote work?",
  "dataSource": "sharePoint",
  "resourceMetadata": [
    "title",
    "author"
  ],
  "maximumNumberOfResults": 10
}

Das war’s. Eine natürlichsprachige Query, eine Datenquelle, und optional welche Metadaten du zurück haben willst.

4. Die Response parsen

Die Response liefert dir ein Array von Retrieval Hits, jeder mit Text-Extracts und Relevance Scores:

{
  "retrievalHits": [
    {
      "webUrl": "https://contoso.sharepoint.com/sites/HR/RemoteWorkPolicy.docx",
      "extracts": [
        {
          "text": "Employees may work remotely up to three days per week with manager approval. Remote work arrangements must be documented...",
          "relevanceScore": 0.8374
        },
        {
          "text": "All remote workers must use the corporate VPN and comply with the data handling policy outlined in section 4.2.",
          "relevanceScore": 0.7465
        }
      ],
      "resourceType": "listItem",
      "resourceMetadata": {
        "title": "Remote Work Policy 2025",
        "author": "HR Department"
      },
      "sensitivityLabel": {
        "sensitivityLabelId": "f71f1f74-bf1f-4e6b-b266-c777ea76e2s8",
        "displayName": "Confidential",
        "priority": 4
      }
    }
  ]
}

Ein paar Dinge die auffallen:

• Die extracts sind tatsächliche Text-Chunks, nicht nur Snippets. Graph Search gibt dir winzige Previews. Diese sind lang genug, um eine LLM-Antwort direkt zu grounden.
• relevanceScore ist eine Cosine Similarity zwischen deiner Query und dem Extract, normalisiert auf 0-1.
• sensitivityLabel kommt automatisch zurück. Dein Orchestrator kann das nutzen, um zu entscheiden was angezeigt wird.
• Ergebnisse sind unsortiert. Geh nicht davon aus, dass der erste Hit der beste ist – schick alle Extracts an dein LLM.

5. Mit KQL-Filtern einschränken

Du kannst KQL-Ausdrücke verwenden, um Retrieval auf bestimmte Sites, Dateitypen, Datumsbereiche oder Autoren einzuschränken. Hier wird es richtig nützlich:

POST https://graph.microsoft.com/v1.0/copilot/retrieval
Content-Type: application/json
Authorization: Bearer {access-token}

{
  "queryString": "quarterly revenue targets",
  "dataSource": "sharePoint",
  "filterExpression": "path:\"https://contoso.sharepoint.com/sites/Finance/\" AND FileExtension:\"pptx\" AND LastModifiedTime>= 2025-07-01",
  "resourceMetadata": ["title", "author"],
  "maximumNumberOfResults": 15
}

Unterstützte SharePoint-Filter-Properties: Author, FileExtension, Filename, FileType, InformationProtectionLabelId, LastModifiedTime, ModifiedBy, Path, SiteID und Title. Du kannst sie mit AND, OR und NOT kombinieren.

Ein Gotcha: Wenn deine KQL-Syntax ungültig ist, führt die API den Aufruf still und leise ohne Filterung aus, statt einen Fehler zu werfen. Prüf deine Ausdrücke lieber doppelt.

Retrieval API vs. Graph Search vs. Copilot Search

Das ist die Frage, die ich ständig gestellt bekomme. Microsoft hat jetzt drei verschiedene Wege, Enterprise-Content programmatisch zu durchsuchen. So denke ich darüber nach:

Die Kurzversion: Graph Search ist zum Dokumente finden. Die Retrieval API ist zum Content an ein LLM füttern. Copilot Search ist die neuere semantische Suche speziell für OneDrive, mit mehr Datenquellen später.

Wenn du einen Custom AI Agent oder eine RAG Pipeline baust, ist die Retrieval API fast sicher das was du willst. Sie liefert genug Text, um tatsächlich eine Antwort zu grounden, und sie kümmert sich um die harten Teile – Chunking, semantisches Ranking, Permission Trimming – für dich.

Batch Requests für Multi-Source Retrieval

Da die API erfordert, dass du pro Request eine Datenquelle angibst, wirst du oft SharePoint und Copilot Connectors parallel abfragen wollen. Der Graph Batch Endpoint handhabt das sauber – bis zu 20 Requests pro Batch:

POST https://graph.microsoft.com/v1.0/$batch
Content-Type: application/json
Authorization: Bearer {access-token}

{
  "requests": [
    {
      "id": "1",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "What is our data retention policy?",
        "dataSource": "sharePoint",
        "maximumNumberOfResults": 10
      },
      "headers": { "Content-Type": "application/json" }
    },
    {
      "id": "2",
      "method": "POST",
      "url": "/copilot/retrieval",
      "body": {
        "queryString": "What is our data retention policy?",
        "dataSource": "externalItem",
        "maximumNumberOfResults": 10
      },
      "headers": { "Content-Type": "application/json" }
    }
  ]
}

Dein Orchestrator bekommt beide Ergebnismengen in einem einzigen Roundtrip, merged die Extracts und schickt sie an das LLM.

Kostenrechnung

Lass mich eine schnelle Überschlagsrechnung für das Pay-as-you-go-Modell machen.

Sagen wir, du baust einen internen Knowledge-Assistenten für 200 Mitarbeiter. Jeder Mitarbeiter stellt im Schnitt 5 Fragen pro Tag, und jede Frage löst 2 Retrieval-Aufrufe aus (einen an SharePoint, einen an Copilot Connectors über Batch). Das sind 200 x 5 x 2 = 2.000 API-Aufrufe pro Tag, oder rund 44.000 pro Monat.

Bei $0,10 pro Aufruf sind das $4.400 pro Monat.

Vergleich das mit der Lizenzierung aller 200 User mit Copilot bei $30/User/Monat: $6.000 pro Monat. Und das ist nur für den Retrieval-Teil – mit Copilot-Lizenzen würden die User das volle Copilot-Erlebnis bekommen, was vielleicht mehr ist als du brauchst.

Der Break-even hängt komplett von deinem Nutzungsmuster ab. Bei geringer Nutzung (ein paar Aufrufe pro User pro Tag) gewinnt Pay-as-you-go. Bei Apps die die API ständig hämmern, könnten Per-User-Lizenzen tatsächlich günstiger sein.

Pass auf das Throttling-Limit von 200 Requests pro User pro Stunde auf. Für Burst-lastige Workloads musst du drumherum designen.

Einschränkungen

Bevor du all-in gehst, hier die praktischen Constraints:

• Maximal 1.500 Zeichen für queryString.
• Maximal 25 Ergebnisse pro Aufruf.
• Eine Datenquelle pro Request. Keine verschränkten Ergebnisse. Verwende Batch Requests als Workaround.
• Dateigrößenlimits: 512 MB für .docx, .pptx, .pdf Dateien; 150 MB für alles andere.
• Semantisches Retrieval funktioniert nur für .doc, .docx, .pptx, .pdf, .aspx und .one Dateien. Andere Erweiterungen fallen auf lexikalisches Retrieval zurück.
• Kein Bild- oder Chart-Content. Nur Text wird abgerufen. Tabellen in .doc, .docx und .pptx werden unterstützt.
• Nur Global Service. Noch keine US Government oder China (21Vianet) Deployments.
• Pay-as-you-go beinhaltet keinen OneDrive-Zugriff. Nur SharePoint und Copilot Connectors.

Wie alles zusammenpasst

Der typische Integrationsablauf sieht so aus:

1. User stellt eine Frage in deiner App.
2. Dein Orchestrator schickt die Query an die Retrieval API (eventuell ein Batch Request über mehrere Datenquellen).
3. Die API liefert permission-trimmed Text-Extracts zurück.
4. Dein Orchestrator schickt diese Extracts als Kontext an dein LLM (Azure OpenAI, oder was auch immer du verwendest).
5. Das LLM generiert eine gegroundete Antwort.
6. Deine App zeigt die Antwort mit Quellenzitaten an (über die webUrl aus jedem Hit).

Das funktioniert mit Azure AI Foundry, Semantic Kernel, LangChain oder jeder Custom-Orchestrierung. Die Retrieval API ist einfach ein REST Endpoint – es ist ihr egal was auf der anderen Seite ist.

Für Microsoft Foundry User: Das SharePoint Tool verwendet die Retrieval API bereits unter der Haube. Wenn du Agents in Foundry baust, bekommen Pay-as-you-go User das automatisch.

Was ich denke, was das bedeutet

Das Preismodell ist hier das Entscheidende, nicht die API selbst. Dass Microsoft sich um Chunking, Ranking und Berechtigungen kümmert, ist ein netter Zeitsparer, klar. Aber die Per-User-Copilot-Lizenz-Anforderung war das, was die meisten Custom-App-Szenarien vom Tisch gefegt hat. Diese Hürde zu entfernen – naja, größtenteils zu entfernen, du brauchst nach wie vor eine Copilot-Lizenz im Tenant – ist das, was es tatsächlich nutzbar macht.

Ich erwarte, dass das Pay-as-you-go-Modell mit der Zeit auf andere Copilot APIs erweitert wird. Und wenn die Copilot Search API SharePoint- und Connector-Support bekommt, wird die Grenze zwischen Retrieval und Search verschwimmen.

Wenn du bisher RAG Pipelines mit Graph Search gebaut und Snippets zusammengestoppelt hast, die nie für LLM Grounding gedacht waren – schau dir das an. Gleiche Daten, bessere Extracts, ordentliche Security, und ein Preismodell bei dem du kein Spreadsheet brauchst um es zu rechtfertigen.

Probier es im Graph Explorer aus. Fünf Minuten und du wirst sehen was ich meine.

Weiterlesen

• Microsoft DevBlog: Unlocking Enterprise Knowledge for AI with the Retrieval API – die offizielle Ankündigung von Zakiullah Khan mit Use Cases und Datenquellen-Übersicht
• Microsoft Learn: Copilot Retrieval API Referenz – vollständige API-Dokumentation inklusive Request/Response-Schemas und Berechtigungen
• Microsoft Learn: Pay-as-you-go Billing für Copilot APIs – Setup-Anleitung und Preisdetails für das Verbrauchsmodell
• Microsoft Learn: Copilot APIs Übersicht – das breitere Set an Copilot APIs über Retrieval hinaus