Skip to content

Copilot Interactions Content Audit Log Processor v1.0.0

Choose a tag to compare

View all tags
@Rance9 Rance9 released this 20 Nov 13:07
· 80 commits to release since this release
copilotinteractions-v1.0.0
7bb69d3
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Release Notes: v1.0.0

Release Information

  • Version: 1.0.0
  • Release Date: 2025-11-19
  • Released By: Brian Middendorf (@microsoft)
  • Previous Version: N/A (Initial Release)

⚠️ Important Usage & Compliance Disclaimer

Please note:

While this tool helps customers better understand their Microsoft 365 Copilot interaction data, Microsoft has no visibility into the data that customers input into this script/tool, nor does Microsoft have any control over how customers will use this script/tool in their environment.

Customers are solely responsible for securing, storing, and processing all exported data in compliance with their organization's policies and all applicable laws and regulations, including but not limited to data privacy, security, and regulatory requirements (e.g., GDPR, HIPAA, PCI DSS, and data residency obligations).

This script outputs highly sensitive Copilot interaction content, including user prompts and Copilot responses, which may contain confidential, regulated, or personally identifiable information (PII). By using this script, you acknowledge and agree:

  • You must implement appropriate safeguards, including encryption, access controls, and data classification, before running or sharing outputs generated by this script.
  • Do not run this script on shared or unmanaged devices. Ensure that only authorized personnel have access to the exported data.
  • Apply data loss prevention (DLP) policies and sensitive information detection where possible.

Microsoft provides this script "as-is" without warranties of any kind and disclaims all liability for any loss, breach, or misuse of data arising from or related to your use of this script. Microsoft does not provide support for custom modifications or downstream uses of this script. All operational risk and compliance obligations rest with you.

✅ Additional Guidance

Consult Your Compliance Team
Before using this script, consult your organization's legal and compliance teams to confirm that your planned usage aligns with internal policies and external regulatory requirements.

Retention & eDiscovery Obligations
Data exported by this script may fall under retention, legal hold, or eDiscovery obligations. Ensure that your organization's compliance policies are applied to any exported files.

🔐 Security Best Practices Checklist
  • ☑ Rotate credentials regularly (client secrets or certificates) and never hard-code secrets in scripts.
  • ☑ Run only in secure environments (managed devices, trusted networks).
  • ☑ Apply encryption at rest and in transit for all exported files.
  • ☑ Restrict access to exported data to authorized personnel only.
  • ☑ Enable DLP and sensitivity labels to prevent accidental sharing.
  • ☑ Validate storage location (e.g., secure SharePoint or encrypted file share).
  • ☑ Review logs and outputs for sensitive content before distribution.
  • ☑ Apply retention and deletion policies to exported data in line with compliance requirements.
🧪 Experimental Script Notice

This is an experimental script. On occasion, you may notice small deviations from metrics in the official Microsoft 365 Copilot Dashboards. We will continue to iterate based on your feedback. Currently available in English only.

Overview

Version 1.0.0 is the initial release of the Copilot Interactions Content Audit Log Processor, designed to export and analyze detailed Microsoft 365 Copilot interaction content including user prompts and AI responses. This script leverages the Microsoft Graph API aiInteraction resource type, providing organizations with comprehensive visibility into Copilot usage patterns, prompt analysis, and content security.

Key Features

1. Content-Rich Copilot Interaction Export

  • Access detailed Microsoft 365 Copilot interaction data via Microsoft Graph API
  • Includes user prompts (Body field when -IncludeBody used)
  • Captures AI responses, interaction metadata, and timestamp information
  • Supports interaction types: userPrompt and aiResponse

2. Flexible Export Options

  • CSV Export: Default output format with UTF-8 encoding
  • Excel Workbooks: Single-sheet exports via -ExportWorkbook parameter
    • Auto-formatted columns with frozen headers
    • Timestamp-based file naming for easy identification
    • Optional user enrichment data included when -IncludeUserInfo used
  • Append Mode: -AppendFile adds new data to existing export files for cumulative datasets
    • Works with both CSV and Excel formats
    • Validates schema compatibility before appending
    • Enables building consolidated exports over time
  • User Enrichment: Optional -IncludeUserInfo for Entra ID user profile data and MAC licensing
  • User-Only Mode: -OnlyUserInfo exports only Entra ID user directory and MAC licensing (no interaction data) for fast license snapshots

3. Incremental Export with Watermarks (-UseWatermark)

  • Efficient incremental exports: Track last processed interaction timestamp per user
  • Automatic state management: Watermark files store last export position for each user
  • Rolling audit trails: Build cumulative datasets with daily/scheduled updates
  • Early-exit optimization: Stops pagination when reaching previously seen timestamps
  • File-based persistence: Simple JSON watermark files for easy monitoring and management

4. Flexible Date Range Controls

  • Custom date ranges: -StartDate and -EndDate parameters for historical analysis
  • Days-back calculation: -DaysBack parameter for relative date ranges (default: 180 days)
  • Timezone handling: Input dates interpreted as local timezone, all output timestamps exported in UTC
  • Cross-timezone consistency: UTC output enables consistent analysis across global organizations

5. Enterprise-Grade Authentication

  • App-only authentication: Uses client credentials flow (OAuth 2.0) with Microsoft Entra ID app registration
  • Service principal execution: Requires -TenantId, -ClientId, -ClientSecret for unattended operation
  • Environment variable support: Credentials can be set via $env:GRAPH_TENANT_ID, $env:GRAPH_CLIENT_ID, $env:GRAPH_CLIENT_SECRET
  • No interactive authentication: Designed for scheduled/automated execution without user prompts

6. Progress Monitoring and Logging

  • Real-time progress indicators: Detailed console output showing API query status
  • Comprehensive logging: Export summaries with record counts and timing information
  • Error handling: Graceful handling of API throttling, network issues, and authentication failures
  • Metrics export: Optional -EmitMetricsJson for performance tracking

7. Network Resilience and Pagination

  • Automatic retry logic: Handles transient Graph API failures with exponential backoff
  • Intelligent throttling: Respects API rate limits and retry-after headers
  • Large dataset support: Efficient pagination for multi-thousand interaction exports
  • Token refresh: Automatic token renewal for long-running operations

8. Output Customization

  • Configurable output paths: -OutputPath parameter for custom export locations
  • Timestamp-based file naming: Automatic timestamped filenames prevent overwrites
  • International character support: UTF-8 encoding for CSV exports, native Unicode support in Excel workbooks
  • Column order preservation: Consistent schema across export formats

9. Filtering and Query Options

  • User-specific queries: Filter by specific users via -UserPrincipalNames or -UserListFile
  • App-specific filtering: Focus on particular Microsoft 365 applications via -CopilotApps
  • Date range filtering: Custom date ranges with -StartDate, -EndDate, or -DaysBack
  • Content filtering: Optional body content inclusion with -IncludeBody and -MaxBodyLength

Key Improvements

The CopilotInteractions Content Audit Log Processor brings enterprise-grade Copilot content analysis to Microsoft 365 administrators through:

1. Direct Graph API Integration

  • First-class Microsoft Graph API support: Access aiInteraction resource type directly
  • No intermediate data stores required: Direct query from Microsoft 365 backend
  • App-only authentication: Microsoft Entra ID service principal with client credentials flow
  • Future-proof architecture: Built on Microsoft's recommended API patterns

2. Content-Rich Analysis

  • Full interaction context: Access to user prompts, AI responses, and metadata
  • Deep content inspection: Enable content auditing with -IncludeBody parameter
  • Comprehensive metadata: Timestamps, interaction types, app context, session information
  • Structured data export: Clean, normalized CSV/Excel formats for downstream analysis

3. Enterprise Scalability

  • Efficient pagination: Handle millions of interactions across large organizations
  • Incremental exports: Build cumulative datasets with watermark-based resumption
  • Network resilience: Automatic retry logic and throttle handling
  • Scheduled execution support: Service principal auth for automated/unattended runs

4. Flexible Output and Enrichment

  • Multiple export formats: CSV for data pipelines, Excel for human analysis
  • User profile enrichment: Optional Entra ID lookups for department, title, location, and MAC licensing
  • Formatted Excel workbooks: Auto-formatted columns with frozen headers for easy navigation
  • International character support: UTF-8 encoding for CSV, native Unicode support in Excel workbooks

5. Security and Compliance Focus

  • Content audit trail: Track what users ask and what Copilot returns
  • Sensitive data identification: Enable security teams to review interaction content
  • License compliance: Correlate usage with M365 Copilot license assignments
  • Retention policy support: Build archives for regulatory compliance requirements

Why This Release Matters

Version 1.0.0 enables organizations to answer critical questions about Microsoft 365 Copilot usage and content:

Key Question How CopilotInteractions Helps
What are users asking Copilot? Exports user prompts (Body field) for content analysis and sensitive data review
What is Copilot responding with? Captures AI responses for quality assurance and compliance verification
Who is using Copilot most actively? Interaction counts per user with optional Entra ID enrichment (department, title, location, MAC licensing)
Which apps generate the most interactions? App context tracking for usage pattern analysis
Are we respecting data retention policies? Build audit archives with watermark-based incremental exports
Can we identify sensitive content exposure? Full-text search capabilities across prompts and responses for DLP analysis

Business Impact:

  • Security Teams: Identify and remediate sensitive data exposure in Copilot interactions
  • Compliance Officers: Demonstrate content retention and audit trail capabilities for regulatory requirements
  • License Managers: Validate Copilot license utilization and identify inactive users
  • IT Administrators: Monitor adoption patterns and troubleshoot user-reported issues with interaction history

What's Included in v1.0.0

Core Script

PAX_CopilotInteractions_Content_Audit_Log_Processor_v1.0.0.ps1

Key Parameters

# User Selection
-UserPrincipalNames <String[]>    # Specific user(s) to query
-UserListFile <String>            # File with list of users (one per line)

# Date Range Controls
-StartDate <DateTime>             # Query start date (input: local timezone, queries converted to UTC)
-EndDate <DateTime>               # Query end date (input: local timezone, queries converted to UTC)
-DaysBack <Int>                   # Days back from EndDate (default: 180)

# App Filtering
-CopilotApps <String[]>           # Filter by app (Word, Excel, PowerPoint, Outlook, Teams, BizChat, etc.)

# Content Options
-IncludeBody                      # Include user prompts in Body field
-MaxBodyLength <Int>              # Max characters for Body field (default: 10000)
-IncludeUserInfo                  # Enrich with Entra ID user profiles and MAC licensing
-OnlyUserInfo                     # Export only Entra ID users and MAC licensing (no interactions)
-IncludeStats                     # Generate usage statistics by user, app, and date

# Export Formats
-OutputPath <String>              # Custom export directory (default: C:\Temp)
-ExportWorkbook                   # Export to Excel instead of CSV

# Incremental Processing
-UseWatermark                     # Enable watermark-based incremental exports
-WatermarkFile <String>           # Custom watermark file path (default: copilot-watermarks.json)
-AppendFile <String>              # Append to existing file

# Authentication (Service Principal)
-TenantId <String>                # Microsoft Entra ID Tenant ID
-ClientId <String>                # Entra ID App Registration Client ID
-ClientSecret <String>            # Entra ID App Registration Client Secret

# Performance
-ParallelBatchThrottle <Int>      # Concurrent user queries (default: 25)
-ParallelMode <String>            # Auto/On/Off (default: Auto)

# Metrics & Diagnostics
-EmitMetricsJson                  # Generate performance metrics JSON
-MetricsPath <String>             # Custom metrics output path
-Help                             # Display help information

Core Features

✅ Microsoft Graph API aiInteraction resource type integration
✅ Content-rich exports with user prompts and AI responses
✅ Optional Entra ID user enrichment with MAC licensing
✅ CSV and Excel export formats
✅ Incremental export with watermark state management
✅ Append mode for cumulative datasets (-AppendFile)
✅ Service principal authentication for automation
✅ Network resilience with automatic retry logic
✅ International character support (UTF-8 for CSV, Unicode for Excel)
✅ Flexible date range controls (StartDate/EndDate/DaysBack)
✅ Usage statistics export with -IncludeStats

Installation

Download v1.0.0 (This Version)

Use the direct download link below to obtain this specific version:

Related Assets

Prerequisites

  • PowerShell: 5.1 or later (PowerShell 7+ recommended for parallel processing performance)
  • Microsoft Graph PowerShell SDK: Auto-installed by script if missing (Microsoft.Graph.Authentication module)
  • ImportExcel Module: Auto-installed by script if missing (required only when using -ExportWorkbook)
  • Microsoft Entra ID App Registration: Required with the following Application permissions (all three required for every script run):
    • AiEnterpriseInteraction.Read.All - Read Copilot interaction history for all users
    • User.Read.All - Read user directory and license information
    • Organization.Read.All - Read organization and related resources
    • All permissions require tenant admin consent

Support

For questions or issues, refer to the documentation:

Managed and released by the Microsoft Copilot Growth ROI Advisory Team. Please reach out to copilot-roi-advisory-team-gh@microsoft.com with any feedback.

Summary

v1.0.0 introduces the CopilotInteractions Content Audit Log Processor, enabling organizations to export and analyze detailed Microsoft 365 Copilot interaction content including user prompts and AI responses through direct Microsoft Graph API integration.

Key Capabilities:

  • Content-rich exports with user prompts (-IncludeBody) and AI responses
  • Optional Entra ID user enrichment with MAC licensing for organizational analysis
  • Incremental exports with watermark-based state management
  • Flexible CSV and Excel output formats
  • Enterprise-ready authentication and scheduling support

Use Cases:

  • Security teams: Identify sensitive data exposure in Copilot interactions
  • Compliance officers: Build audit trails for regulatory requirements
  • License managers: Validate Copilot license utilization
  • IT administrators: Monitor adoption patterns and troubleshoot issues

Enjoy the release and keep the feedback coming.

Contributors

microsoft
Assets 3
Loading