Ever wonder how to get a clear, detailed picture of your Exchange Online or hybrid migration progress? This comprehensive guide will walk you through mastering the Get-MigrationBatch cmdlet, covering its essential permissions, powerful filtering with -Filter, detailed reporting via -IncludeReport, and practical examples for monitoring and troubleshooting your mailbox moves.
Key Takeaways
- The Get-MigrationBatch cmdlet is used to retrieve information about one or more migration batches in Exchange Online or on-premises Exchange servers configured for hybrid deployments
- Get-MigrationBatch requires the Migration Administrator role or higher permissions to execute successfully in Exchange Online PowerShell
- The cmdlet supports filtering migration batches by status such as Creating, Initializing, Syncing, or Completed using the -Filter parameter with OPath syntax
- The Identity parameter accepts batch GUIDs, names, or wildcards for Get-MigrationBatch
- -Filter parameter uses OPath filters like 'Status -eq "Synced"' for precise querying
- -IncludeReport switch expands output to include BadItemsEncounteredCount per mailbox
- The Identity property uniquely identifies batches as GUID strings
- Status property values include Queued, InProgress, Completed, Failed, Synced
- TotalMailboxCount indicates the total number of mailboxes targeted in the batch
- Example: Get-MigrationBatch | Select Identity,Status,TotalMailboxCount retrieves key metrics
- To list failed batches: Get-MigrationBatch -Filter 'FailedMailboxCount -gt 0' | Format-Table Identity,FailedMailboxCount
- Detailed report: Get-MigrationBatch 'Batch1' -IncludeReport | Format-List Report
- Throttling delays occur if querying more than 100 batches rapidly; implement Start-Sleep 1 between calls
- Error 'The term Get-MigrationBatch is not recognized' indicates missing ExchangeOnlineManagement module; run Install-Module ExchangeOnlineManagement
- Filter syntax errors like invalid property names return A parameter cannot be found; validate with Get-MigrationBatch | Get-Member
This blog post explains how to use Get-MigrationBatch for managing Exchange mailbox migrations.
Best Practices and Troubleshooting
- Throttling delays occur if querying more than 100 batches rapidly; implement Start-Sleep 1 between calls
- Error 'The term Get-MigrationBatch is not recognized' indicates missing ExchangeOnlineManagement module; run Install-Module ExchangeOnlineManagement
- Filter syntax errors like invalid property names return A parameter cannot be found; validate with Get-MigrationBatch | Get-Member
- High latency in responses suggests MRSProxy overload; check Get-MoveRequestStatistics for bottlenecks
- Permission denied: Ensure Organization Management or Mailbox Import Export roles assigned via New-RoleGroup
- Empty results on valid query: Verify batch exists with Get-MigrationBatch without filters first
- -IncludeReport fails with memory issues for large batches (>500 mailboxes); use paging or no report
- Timeouts in REST PowerShell: Increase $MaximumExecutionTime parameter in Connect-ExchangeOnline
- Invalid filter operators cause ParameterBindingValidationException; use -eq, -gt, -like only
- Batches not visible due to RBAC scoping; use -Filter on accessible batches or elevate roles
- Performance tip: Limit to -Filter 'Status -eq "InProgress"' instead of all batches
- Audit failed queries: Search-UnifiedAuditLog for Get-MigrationBatch operations post-error
- DomainController unreachable: Results in RPC errors; specify alternative DC or remove parameter
- Progress stuck at 0%: Check firewall blocks to MRSProxy endpoint outlook.office365.com:443
- Use try-catch for scripting: try { Get-MigrationBatch } catch { Write-Error $_.Exception.Message }
- Large reports exceed cmdlet buffer; pipe to Out-File incrementally
- Version mismatch: Ensure module version >2.0.5 for full property support; Update-Module ExchangeOnlineManagement
- Multi-factor auth issues: Use Connect-ExchangeOnline -UseDeviceAuthentication for headless scripts
- Filter on non-existent properties returns no error but empty results; list properties first
- Best practice: Disconnect-ExchangeOnline after queries to free sessions
- Correlate with Get-MoveRequest for per-mailbox details under batches
Best Practices and Troubleshooting Interpretation
Think of troubleshooting 'Get-MigrationBatch' as a culinary art: you must preheat your permissions, measure your filters precisely, rest your calls to avoid throttling, and constantly taste-test with error handling to ensure your large, complex batch doesn't end up as a burnt offering.
Cmdlet Overview
- The Get-MigrationBatch cmdlet is used to retrieve information about one or more migration batches in Exchange Online or on-premises Exchange servers configured for hybrid deployments
- Get-MigrationBatch requires the Migration Administrator role or higher permissions to execute successfully in Exchange Online PowerShell
- The cmdlet supports filtering migration batches by status such as Creating, Initializing, Syncing, or Completed using the -Filter parameter with OPath syntax
- Get-MigrationBatch can display extended reports including per-mailbox details when used with the -IncludeReport switch
- In hybrid deployments, Get-MigrationBatch shows batches for mailbox moves between on-premises and Exchange Online
- The cmdlet returns objects of type Microsoft.Exchange.Management.PowershellII.MigrationBatch
- Get-MigrationBatch does not support public folder migrations; use Get-PublicFolderMigrationRequest for those
- Execution of Get-MigrationBatch counts towards PowerShell throttling limits in Exchange Online
- The cmdlet is available in Exchange Online PowerShell V2 and V3 modules
- Get-MigrationBatch lists batches created via New-MigrationBatch or the Exchange Admin Center
- By default, Get-MigrationBatch without parameters returns all migration batches in the organization
- The cmdlet supports piping output to Format-List or Export-Csv for detailed viewing or logging
- Get-MigrationBatch respects organizational scopes and role-based access control (RBAC) permissions
- Historical migration batches are retained for 30 days after completion before auto-removal
- The cmdlet can query batches in Queued, InProgress, or Failed states with specific filters
- Get-MigrationBatch is not supported in standalone on-premises Exchange without hybrid configuration
- Output from Get-MigrationBatch includes batch submission time and last modified timestamp
- The cmdlet integrates with Azure AD Connect for identity synchronization during migrations
- Get-MigrationBatch supports CSV output for integration with monitoring tools like SCOM
- Multi-tenant organizations may see batches scoped to specific tenants via filters
- The cmdlet logs activities to the Exchange Unified Audit Log for compliance
- Get-MigrationBatch performance is optimized for up to 1000 batches per query
- It requires PowerShell 5.1 or later for full compatibility with Exchange Online
- Get-MigrationBatch can be scheduled via Task Scheduler for regular reporting
- The cmdlet supports internationalization with localized status messages
- It provides visibility into MRSProxy endpoint usage during migrations
- Get-MigrationBatch is part of the ExchangeOnlineManagement module version 3.0+
- The cmdlet does not alter batch states; it's read-only
- It supports REST-based PowerShell connections for reduced latency
- Get-MigrationBatch integrates with Microsoft Graph for advanced reporting via APIs
Cmdlet Overview Interpretation
Think of Get-MigrationBatch as your migration command center, offering a read-only, permission-gated, and throttled panoramic view of your organization's mailbox relocations, complete with detailed reports and a 30-day memory, but it politely declines to touch your public folders.
Output Properties
- The Identity property uniquely identifies batches as GUID strings
- Status property values include Queued, InProgress, Completed, Failed, Synced
- TotalMailboxCount indicates the total number of mailboxes targeted in the batch
- FailedMailboxCount tracks mailboxes that could not be migrated successfully
- PercentComplete is a double value from 0.0 to 100.0 representing progress
- SubmissionTime is a DateTime showing when the batch was submitted
- LastModifiedTime updates dynamically during batch lifecycle changes
- TotalCount aggregates total mail items across all mailboxes in the batch
- BadItemLimit is the configured threshold for bad items before failure
- Report property is a string containing HTML-formatted migration details with -IncludeReport
- MigrationType distinguishes between IntraOrg, CrossOrg, or RemoteMove batches
- ProcessedMailboxCount shows successfully processed mailboxes to date
- SyncMailboxCount for incremental sync passes in staged migrations
- EstimatedCompletionTime predicts finish based on current throughput
- BytesTransferred accumulates total data volume migrated in GB
- LargestMailboxSize identifies the biggest mailbox impacting throughput
- NotificationEmails lists recipients for batch status alerts
- AutoStartTime schedules automatic batch initiation if set
- TimeToCompleteCutoverAfterAllBatchesComplete for cutover timing
- The output object has 50+ properties accessible via Select-Object
- DisplayName is a user-friendly name for the migration batch
- The StatusDetail property provides granular sub-status like InitializingProxy
- TotalMailboxItemCount sums items across all mailboxes pre-migration
- AcceptLargeDataLoss flag indicates tolerance for data loss over limits
- The cmdlet returns MigrationBatch objects with methods like ToString() overridden
Output Properties Interpretation
Think of the Get-MigrationBatch cmdlet as a high-stakes, bureaucratic stage manager for a chaotic data parade, meticulously tracking everything from the size of the biggest float (LargestMailboxSize) and the number of dropped confetti (FailedMailboxCount) to when the after-party emails (NotificationEmails) get sent.
Parameters Details
- The Identity parameter accepts batch GUIDs, names, or wildcards for Get-MigrationBatch
- -Filter parameter uses OPath filters like 'Status -eq "Synced"' for precise querying
- -IncludeReport switch expands output to include BadItemsEncounteredCount per mailbox
- -DomainController parameter is used only in on-premises hybrid scenarios for DC affinity
- No positional parameters are supported; all must be named explicitly
- -Filter supports complex queries like '(Status -eq "Failed") -and (TotalCount -gt 10)'
- The cmdlet accepts pipeline input for Identity from other migration cmdlets
- -IncludeReport increases response size by up to 10x due to detailed per-item reports
- Parameters are case-insensitive, following PowerShell conventions
- -DomainController accepts FQDN or NetBIOS names of domain controllers
- Common filters include 'FailedMailboxesCount -gt 0' to find problematic batches
- The Identity parameter supports multiple values separated by commas
- -Filter does not support property wildcards; exact property names required
- Parameters like -Filter are validated at runtime against available properties
- -IncludeReport is mutually exclusive with lightweight queries for performance
- Pipeline input type is Microsoft.Exchange.Management.PowershellII.MigrationBatch for Identity
- -DomainController defaults to any available DC if not specified
- Filter properties include PercentComplete, calculated as (ProcessedCount / TotalCount) * 100
- All parameters support tab-completion in ISE or VS Code PowerShell extensions
- -Filter syntax errors result in ParameterBindingException
- Identity wildcards like 'Batch*' match multiple batches efficiently
- Parameters are serialized in REST API calls for remote PowerShell
- -IncludeReport requires additional RBAC for report data access
- Filter on SubmissionTime with DateTime operators like -gt '2023-01-01'
Parameters Details Interpretation
The Get-MigrationBatch cmdlet lets you track your email migrations with surgical precision—from a simple status check to an exhaustive, performance-hogging post-mortem report—provided you follow its strict syntax rules and can handle the verbose truth.
Usage Examples
- Example: Get-MigrationBatch | Select Identity,Status,TotalMailboxCount retrieves key metrics
- To list failed batches: Get-MigrationBatch -Filter 'FailedMailboxCount -gt 0' | Format-Table Identity,FailedMailboxCount
- Detailed report: Get-MigrationBatch 'Batch1' -IncludeReport | Format-List Report
- Export all batches to CSV: Get-MigrationBatch | Export-Csv -Path C:\MigrationBatches.csv -NoTypeInformation
- Filter by status and date: Get-MigrationBatch -Filter "(Status -eq 'Completed') -and (SubmissionTime -gt '2023-01-01')"
- Pipeline from New-MigrationBatch: New-MigrationBatch ... | Get-MigrationBatch
- Monitor progress: while($true) { Get-MigrationBatch | Where PercentComplete -lt 100; Start-Sleep 300 }
- Get batches by type: Get-MigrationBatch -Filter "MigrationType -eq 'RemoteMove'"
- Sort by completion time: Get-MigrationBatch | Sort LastModifiedTime -Descending | Select -First 10
- Hybrid DC specific: Get-MigrationBatch -DomainController dc01.contoso.com
- Find slow batches: Get-MigrationBatch | Where PercentComplete -lt 50 -and SubmissionTime -lt (Get-Date).AddDays(-7)
- With error counts: Get-MigrationBatch | Select Identity, FailedMailboxCount, BadItemLimit | Where FailedMailboxCount -gt 0
- Batch details loop: foreach($batch in Get-MigrationBatch) { $batch | FL * }
- Integrate with email alerts: Get-MigrationBatch -Filter 'Status -eq "Failed"' | Send-MailMessage ...
- Wildcard identity: Get-MigrationBatch 'Prod*'
- Progress bar script: Get-MigrationBatch | ForEach { Write-Progress ... }
- Compare batches: $b1 = Get-MigrationBatch 'Batch1'; $b2 = Get-MigrationBatch 'Batch2'; Compare-Object $b1 $b2
- Historical query: Get-MigrationBatch -Filter "SubmissionTime -ge '2023-06-01T00:00:00'"
- Top N batches: Get-MigrationBatch | Sort TotalMailboxCount -Descending | Select -First 5
- JSON export: Get-MigrationBatch | ConvertTo-Json | Out-File batches.json
- Multi-condition filter: Get-MigrationBatch -Filter "(Status -ne 'Completed') -or (FailedMailboxCount -gt 0)"
Usage Examples Interpretation
The provided examples transform the simple act of checking migration batch status into a full IT command center, offering everything from a quick glance at key metrics to automated monitoring, detailed reporting, and strategic filtering to pinpoint everything from slow-moving jobs to historical trends.