Modifier

Get-TenantPrivateChannelMigrationStatus

Module:
MicrosoftTeams PowerShell module

You use the Get-TenantPrivateChannelMigrationStatus cmdlet to check the status of private channel migration for your tenant.

Syntax

Default (Default) 

Get-TenantPrivateChannelMigrationStatus

Description

The Get-TenantPrivateChannelMigrationStatus cmdlet allows tenant administrators to track the status of the private channel migration for their Microsoft Teams organization. More details about the migration can be found in the Microsoft Teams blog in New enhancements in Private Channels in Microsoft Teams unlock their full potentia.

Note: This cmdlet requires tenant administrator permissions to execute.

Examples

Example 1

This example gets the migration status for a tenant where all channels have been migrated.

Get-TenantPrivateChannelMigrationStatus

TenantId                     : 12345678-1234-1234-1234-123456789abc
MigrationStatus              : Completed
MigrationStartTimeStamp      : 2025-10-09T10:15:00.456Z
MigrationCompletionTimeStamp : 2025-10-09T12:45:00.789Z
Details                      : {"totalChannels":10,"migratedChannels":10,"failedChannels":0,"ownerlessChannels":0,"remainingChannels":0}

Example 2

This example gets the migration status for a tenant where some channels require admin attention.

Get-TenantPrivateChannelMigrationStatus

TenantId                     : 94d200e4-2df1-45b9-bc3e-53cfa7cf4997
MigrationStatus              : RequiresAdminAttention
MigrationStartTimeStamp      : 2026-02-10T06:48:20.000Z
MigrationCompletionTimeStamp :
Details                      : {"totalChannels":10,"migratedChannels":6,"failedChannels":1,"ownerlessChannels":2,"remainingChannels":1,"ownerlessChannelsDetails":[{"channelThreadId":"19:70c903e82053408790c3941f614a4d36@thread.tacv2","teamId":"12025f7b-4e7d-4d4c-b597-10f52de1c198"},{"channelThreadId":"19:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6@thread.tacv2","teamId":"b94ac03c-ba25-4e79-89ab-d23f707863f7"}]}

Example 3

This example parses the Details JSON and lists ownerless channels in a table.

$result = Get-TenantPrivateChannelMigrationStatus
$details = $result.Details | ConvertFrom-Json
Write-Host "Total: $($details.totalChannels), Migrated: $($details.migratedChannels), Failed: $($details.failedChannels), Ownerless: $($details.ownerlessChannels)"
if ($details.ownerlessChannelsDetails) { $details.ownerlessChannelsDetails | Format-Table channelThreadId, teamId }

Inputs

None

This cmdlet does not accept pipeline input.

Outputs

System.Object

Returns a PrivateChannelMigrationStatusResponse object with the following properties:

Property Type Description
TenantId String The Microsoft Entra tenant identifier.
MigrationStatus String Overall migration status for the tenant. Possible values: NotStarted, InProgress, Completed, RequiresAdminAttention.
MigrationStartTimeStamp DateTime When migration started for this tenant. Empty if migration has not started.
MigrationCompletionTimeStamp DateTime When migration completed. Only populated when all channels are done.
Details String JSON string containing channel counts and per-channel detail arrays.

Migration status values

Value Description
NotStarted No private channels have been processed for this tenant.
InProgress Migration is underway.
Completed All private channels have been successfully migrated.
RequiresAdminAttention One or more channels were skipped because they have no owners. If these channels are still in use, a tenant admin or Teams service admin can add an owner to unblock migration. Failed channels do not require admin action and are retried automatically.

Details JSON fields

Field Type Description
totalChannels Integer Total number of private channels for this tenant.
migratedChannels Integer Number of channels migrated successfully.
failedChannels Integer Number of channels where migration failed. No admin action is needed.
ownerlessChannels Integer Number of channels skipped because they have no owners.
remainingChannels Integer Number of channels still in progress or not yet started.
ownerlessChannelsDetails Array Per-channel details for ownerless channels. Each entry contains channelThreadId and teamId.

Channel detail object

Field Type Description
channelThreadId String The unique identifier of the private channel.
teamId String The unique identifier (GroupId) of the parent team. This is the same value used by the -GroupId parameter in Get-Team, Get-TeamChannel, and Microsoft Graph team resource.

Notes

  • This cmdlet requires tenant administrator permissions.
  • Private channels remain functional throughout the migration process.
  • The Details property is returned as a JSON string. Use ConvertFrom-Json to parse it.
  • When no ownerless channels exist, the ownerlessChannelsDetails array may be empty or omitted from the JSON.
  • Ownerless channels were skipped because they have no owners. If these channels are still in use, a tenant admin or Teams service admin can add an owner using Add-TeamUser and Add-TeamChannelUser.