team: clone

Namespace: microsoft.graph

Create a copy of a team. This operation also creates a copy of the corresponding group. You can specify which parts of the team to clone:

  • apps - Copies Microsoft Teams apps that are installed in the team.
  • channels – Copies the channel structure (but not the messages in the channel).
  • members – Copies the members and owners of the group.
  • settings – Copies all settings within the team, along with key group settings.
  • tabs – Copies the tabs within channels.


This method isn't supported for organization-wide teams.


A known issue related to owners of cloned teams is associated with this method. For details, see Known issues.

When tabs are cloned, they aren't configured. The tabs are displayed on the tab bar in Microsoft Teams, and the first time a user opens them, they must go through the configuration screen. If the user who opens the tab doesn't have permission to configure apps, they see a message that says that the tab isn't configured.

Cloning is a long-running operation. After the POST clone returns, you need to GET the operation returned by the Location: header to see if it's running, succeeded, or failed. You should continue to GET until the status isn't running. The recommended delay between GETs is 5 seconds.

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet


Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Team.Create Directory.ReadWrite.All, Group.ReadWrite.All
Delegated (personal Microsoft account) Not supported. Not supported.
Application Team.Create Directory.ReadWrite.All, Group.ReadWrite.All


The Group.ReadWrite.All and Directory.ReadWrite.All are supported only for backward compatibility. We recommend that you update your solutions to use an alternative permission listed in the previous table and avoid using these permissions going forward.

HTTP request

POST /teams/{id}/clone

Request headers

Header Value
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json

Request body

Property Type Description
classification String (optional) Describes a classification for the group (such as low, medium, or high business impact). If classification isn't specified, the classification is copied from the original team/group.
description String (optional) An optional description for the group. If this property isn't specified, it's left blank.
displayName String The display name for the group. This property is required when a group is created and it can't be cleared during updates. Supports $filter and $orderby.
mailNickname String The mail alias for the group, unique in the organization. This property must be specified when a group is created. Supports filter. If this property isn't specified, it's computed from the displayName. This property is currently ignored.
partsToClone clonableTeamParts A comma-separated list of the parts to clone. Legal parts are "apps, tabs, settings, channels, members".
visibility teamVisibilityType (optional) Specifies the visibility of the group. Possible values are: Private, Public. If visibility isn't specified, the visibility is copied from the original team/group. If the team being cloned is an educationClass team, the visibility parameter is ignored, and the new group's visibility will be set to HiddenMembership.


If the description property isn't specified in the request body, it takes the value of the displayName property from the request payload.


If successful, this method returns a 202 Accepted response code with a Location: header pointing to the operation resource. When the operation is complete, the operation resource tells you the ID of the created team.



The following example shows a request.

Content-Type: application/json

     "displayName": "Library Assist",
     "description": "Self help community for library",
     "mailNickname": "libassist",
     "partsToClone": "apps,tabs,settings,channels,members",
     "visibility": "public"


The following example shows the response. Note: The response object shown here might be shortened for readability.

HTTP/1.1 202 Accepted
Location: /teams({id})/operations({opId})
Content-Type: text/plain
Content-Length: 0

Microsoft Graph service-specific throttling limits