POWERSHELL COMMAND
Set-XdrEndpointDeviceTag
Sets, adds, or removes user-defined tags on endpoint devices in Microsoft Defender XDR.
Manages user-defined tags on one or more endpoint devices by calling the editMachineTags API. Only modifies UserDefinedTags; BuiltInTags and DynamicRulesTags are managed through separate mechanisms. Supports two modes:
- Replace (Tags): Replaces all existing user-defined tags with the provided tags.
- AddRemove (Add/Remove): Retrieves current user-defined tags, adds and/or removes the specified tags, and sets the resulting list. Both -Add and -Remove can be used together in a single call.
When using -Add or -Remove, the cmdlet fetches each device’s current user-defined tags via Get-XdrEndpointDeviceTag, modifies the list, then calls editMachineTags with the updated set.
Syntax
Set-XdrEndpointDeviceTag -DeviceId <string[]> -Tags <string[]> [-WhatIf] [-Confirm] [<CommonParameters>]
Set-XdrEndpointDeviceTag -DeviceId <string[]> [-Add <string[]>] [-Remove <string[]>] [-WhatIf] [-Confirm] [<CommonParameters>]
Parameters
-DeviceId
| Property | Value |
|---|---|
| Type | String[] |
| Required | Yes |
| Position | named |
| Pipeline input | true (ByPropertyName) |
| Default | Not documented |
One or more device IDs (SenseMachineIds) identifying the target devices.
-Tags
| Property | Value |
|---|---|
| Type | String[] |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Array of tag strings to set on the devices. Replaces all existing user-defined tags.
-Add
| Property | Value |
|---|---|
| Type | String[] |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Array of tag strings to add to each device’s existing user-defined tags. Duplicates are ignored. Can be combined with -Remove in a single call.
-Remove
| Property | Value |
|---|---|
| Type | String[] |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Array of tag strings to remove from each device’s existing user-defined tags. Can be combined with -Add in a single call.
-WhatIf
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Shows what would happen if the command runs. The command is not run.
-Confirm
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Prompts for confirmation before making changes.
Examples
Set-XdrEndpointDeviceTag -DeviceId "abc123" -Tags "Production", "VDI"
Replaces all user-defined tags on the device with Production and VDI.
Set-XdrEndpointDeviceTag -DeviceId "abc123" -Add "VDI"
Adds the VDI tag to the device's existing user-defined tags without removing any.
Set-XdrEndpointDeviceTag -DeviceId "abc123" -Remove "TestTag"
Removes the TestTag from the device, keeping all other user-defined tags.
Set-XdrEndpointDeviceTag -DeviceId "abc123" -Add "Production" -Remove "TestTag"
Adds the Production tag and removes the TestTag in a single operation.
Set-XdrEndpointDeviceTag -DeviceId "abc123", "def456" -Add "Production"
Adds the Production tag to multiple devices.
Output
Type: Object
Returns the API response.