> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebuly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft 365 Copilot

> Sync Microsoft 365 Copilot Enterprise interactions into Nebuly via the Microsoft Graph API

The Microsoft 365 Copilot integration is a self-hosted utility script that pulls Copilot Enterprise interactions from the [Microsoft Graph API](https://learn.microsoft.com/en-us/microsoftteams/export-teams-content-copilot) and ingests each prompt and response into Nebuly as an Interaction.

The data flow is:

Microsoft Graph (licensed users) → Conversations extraction → Nebuly ingestion

The script is incremental and resumable: it tracks a local SQLite cache of already-synced coverage windows, so you can re-run it safely at any time without creating duplicates.

Optionally, you can enable **Purview audit enrichment** to attach models information from Microsoft Purview Copilot audit logs.

The source repository is available [here](https://github.com/nebuly-ai/nebuly-integration-examples/tree/main/microsoft_copilot).

## Prerequisites

* A Microsoft 365 tenant with **Copilot Enterprise** licenses, and an admin who can grant tenant-wide API consent.
* **Python ≥ 3.12** and [Poetry](https://python-poetry.org/docs/#installing-with-the-official-installer) installed on the machine that runs the script.

## Install & run

Clone the integration examples repository, install dependencies, configure your `.env` file, and run the sync:

```bash theme={null}
git clone https://github.com/nebuly-ai/nebuly-integration-examples.git
cd nebuly-integration-examples/microsoft_copilot
poetry install
cp .env.example .env
# Fill in NEBULY_API_KEY, AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
# Optional Purview audit enrichment: see "Purview audit enrichment" below (AUDIT_ENRICHMENT, etc.)
poetry run python -m copilot_sync --from-date 2026-01-01
```

Follow the guide below to retrieve the necessary credentials.

For the complete environment variable reference, available CLI flags, payload customization and resumable-cache details, check the project README.

## Get your credentials

The script requires four environment variables. Follow the steps below to obtain each one: `NEBULY_API_KEY`, `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, and `AZURE_CLIENT_SECRET`.

**1. Nebuly secret key → NEBULY\_API\_KEY**

In Nebuly, go to **Settings → Projects → View Nebuly keys → Secret keys** and copy the secret key for the project you want to sync.

**2. Register an app in Microsoft Entra**

1. Open the [Microsoft Entra admin center](https://entra.microsoft.com).
2. Go to **App registrations → New registration**.
3. Give the app a name.
4. Under **Supported account types**, choose **Single tenant only - \{tenant name}**
5. Click **Register**.

**3. Tenant & client IDs → AZURE\_TENANT\_ID / AZURE\_CLIENT\_ID**

Go to **App registrations → \{app name} → Overview** page, copy:

* **Directory (tenant) ID** → `AZURE_TENANT_ID`
* **Application (client) ID** → `AZURE_CLIENT_ID`

**4. Client secret → AZURE\_CLIENT\_SECRET**

1. Go to **App registrations → \{app name} → Certificates & secrets → New client secret**.
2. Add a description and expiration, then click **Add**.
3. Copy the secret **Value** immediately. Use the Value, not the Secret ID, for `AZURE_CLIENT_SECRET`.

> [!WARNING]
>
> Client secrets expire, so choose an expiration policy you can rotate before it lapses.

**5. Grant API permissions**

1. Go to **App registrations → \{app name} → API permissions → Add a permission**.
2. Select **Microsoft Graph → Application permissions**.
3. Add **`AiEnterpriseInteraction.Read.All`** and **`User.Read.All`**.
4. *(Optional, for Purview audit enrichment)* Add **`AuditLogsQuery.Read.All`** — only required when `AUDIT_ENRICHMENT=true`.
5. Click **Grant admin consent for \{tenant}**.

The permissions are application permissions, not delegated permissions, because the script uses the client-credentials flow. Before running the sync, confirm each permission's **Status** reads **Granted for \{tenant}** with green checks. If it does not, a Global Administrator must approve tenant-wide consent.

## Purview audit enrichment (optional)

When `AUDIT_ENRICHMENT=true`, the sync queries Microsoft Graph [audit log queries](https://learn.microsoft.com/en-us/graph/api/resources/security-auditlogquery?view=graph-rest-1.0) for `CopilotInteraction` records, caches them, and joins them to Graph interaction turns by message id.

> [!WARNING]
>
> Purview audit extraction can take a **long time**, especially on first backfill.
>
> Microsoft runs each [audit log query](https://learn.microsoft.com/en-us/graph/api/resources/security-auditlogquery?view=graph-rest-1.0) **asynchronously** in the background. The sync submits one query per uncovered **day** in your sync window, polls until the job reaches `succeeded` (default up to **1 hour** per chunk via `AUDIT_QUERY_TIMEOUT_SECONDS`), then downloads records. A wide `--from-date` range or a busy tenant means dozens or hundreds of chunks—up to **five** run in parallel—so a single run can last **hours**. Completion time depends on date range, Copilot volume, and Microsoft service load; it is not fixed.
>
> Settled day-chunks are cached locally, so later incremental runs are much faster. If a chunk times out, the sync logs a warning and continues; increase `AUDIT_QUERY_TIMEOUT_SECONDS` or narrow the date range and re-run.

### Enable in `.env`

```bash theme={null}
AUDIT_ENRICHMENT=true
```

Optional tuning (defaults are usually fine):

* `AUDIT_SETTLE_LAG_SECONDS` — default `7200` (hold back the tail while audit records arrive)
* `AUDIT_POLL_INTERVAL_SECONDS` — default `30`
* `AUDIT_QUERY_TIMEOUT_SECONDS` — default `3600`

Copilot audit records often land **60–90 minutes** after the interaction; use the default settle lag on tail syncs. Purview audit data is retained for up to **180 days** (Audit Standard).

### Tags when audit matches

| Tag | Meaning |
| - | - |
| `model_name` / `model_provider` / `model_version` | From model transparency when present |
| `app_host` / `app_identity` | Copilot surface (Office, Teams, etc.) |
| `agent_id` / `agent_name` | Agent metadata when present |
| `plugins` | Comma-separated AI system plugins |
| `web_search` | `true` when Bing web search was used |
| `jailbreak_detected` / `xpia_detected` / `sensitive_resource_accessed` | Set to `true` when applicable |

The most valuable information for Nebuly is the model, as it can be used to enable certain features in the platform.

## FAQ

**Where does the synced data appear?**\
Conversations imported by the script show up on the **Interactions** page in your Nebuly project.

**When will my data appear?**\
There can be a delay of up to 30 minutes between the moment data is available in Microsoft Graph and when it becomes visible in Nebuly. Subsequent updates follow the same polling interval.

**Is it safe to re-run the script?**\
Yes. The script maintains a local SQLite cache at `.cache/sync_state.db` that tracks per-user coverage windows. Re-running it will pick up only new data and will not create duplicates.

**How can I see what would be sent without triggering ingestion?**\
Use the `--dry-run` flag. The script will fetch and convert data but will skip the POST to Nebuly's ingestion endpoint, printing a summary instead.

**Are token, cost, and conversation metrics included?**\
Microsoft Graph does not expose per-interaction token or cost data. Without audit enrichment, the sync sends retrieval (grounding) traces only. With `AUDIT_ENRICHMENT=true`, an LLM trace is added only when Purview provides `ModelName`.

**Why do Excel and PowerPoint Copilot turns appear as separate Nebuly conversations?**\
For Excel and PowerPoint, Microsoft Graph often returns a different `sessionId` (or `requestId`) on each turn, even when the user is continuing the same chat. Nebuly groups turns by that identifier, so multi-turn sessions in those apps usually import as one conversation per turn. This is a limitation of the export data from Microsoft, not the Nebuly sync.

**How do I enable Purview audit enrichment?**\
Grant **`AuditLogsQuery.Read.All`** on your app registration, set `AUDIT_ENRICHMENT=true` in `.env`, and re-run the sync. Expect tail data to appear only after the audit settle window (`AUDIT_SETTLE_LAG_SECONDS`, default 2 hours). See [Purview audit enrichment](#purview-audit-enrichment-optional) above.

## Resources

> [card] [Microsoft 365 Copilot Nebuly integration](https://github.com/nebuly-ai/nebuly-integration-examples/tree/main/microsoft_copilot)
>
> Full install guide, env-var table, CLI flags, and customization docs

> [card] [Export Microsoft Teams Copilot content](https://learn.microsoft.com/en-us/microsoftteams/export-teams-content-copilot)
>
> Microsoft's official guide to exporting Copilot interaction data

> [card] [Microsoft Graph audit log query API](https://learn.microsoft.com/en-us/graph/api/resources/security-auditlogquery?view=graph-rest-1.0)
>
> API used for Purview CopilotInteraction audit enrichment

> [card] [Nebuly Interaction API](https://docs.nebuly.com/tracking/api-reference/events/post-events-interaction-with-trace-v2.md)
>
> API reference for the Interaction ingestion endpoint


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.