Get-XdrEndpointDeviceTimeline
SYNOPSIS
Retrieves the timeline of events for a specific device from Microsoft Defender XDR.
SYNTAX
ByDeviceId (Default)
Get-XdrEndpointDeviceTimeline -DeviceId <String> [-FromDate <DateTime>] [-ToDate <DateTime>]
[-LastNDays <Int32>] [-PageSize <Int32>] [-MarkedEventsOnly] [-SenseClientVersion <String>]
[-SkipIdentityEvents] [-SkipMdiOnlyEvents] [-DoNotUseCache] [-ForceUseCache] [-IncludeSentinelEvents]
[-EventType <String>] [-EventsGroups <String[]>] [-DataTypes <String[]>] [-SourceProviders <String[]>]
[-ThrottleLimit <Int32>] [-TimeoutSeconds <Int32>] [-MaxRetries <Int32>] [-RetryDelaySeconds <Int32>]
[-ChunkHours <Int32>] [-OutputPath <String>] [-KeepTempFiles] [-AllowPartial] [-ExportPath <String>]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
ByMachineDnsName
Get-XdrEndpointDeviceTimeline -MachineDnsName <String> [-FromDate <DateTime>] [-ToDate <DateTime>]
[-LastNDays <Int32>] [-PageSize <Int32>] [-MarkedEventsOnly] [-SenseClientVersion <String>]
[-SkipIdentityEvents] [-SkipMdiOnlyEvents] [-DoNotUseCache] [-ForceUseCache] [-IncludeSentinelEvents]
[-EventType <String>] [-EventsGroups <String[]>] [-DataTypes <String[]>] [-SourceProviders <String[]>]
[-ThrottleLimit <Int32>] [-TimeoutSeconds <Int32>] [-MaxRetries <Int32>] [-RetryDelaySeconds <Int32>]
[-ChunkHours <Int32>] [-OutputPath <String>] [-KeepTempFiles] [-AllowPartial] [-ExportPath <String>]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
Gets the timeline of security events for a device from the Microsoft Defender XDR portal with options to filter by date range and other parameters. Uses parallel chunked requests (1-hour intervals) to improve performance and support longer date ranges up to 180 days.
EXAMPLES
EXAMPLE 1
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2"
Retrieves the last hour of timeline events for the specified device.
EXAMPLE 2
Get-XdrEndpointDeviceTimeline -MachineDnsName "computer.contoso.com"
Retrieves the last hour of timeline events using the machine DNS name.
EXAMPLE 3
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" -FromDate (Get-Date).AddDays(-7) -ToDate (Get-Date)
Retrieves timeline events for the last 7 days using parallel requests.
EXAMPLE 4
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" -LastNDays 90 -ThrottleLimit 5
Retrieves 90 days of timeline events with 5 concurrent requests.
EXAMPLE 5
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" -EventType "Process*"
Retrieves timeline events filtered to process-related events only.
EXAMPLE 6
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" -LastNDays 7 -ExportPath "C:\Reports\timeline.json"
Retrieves 7 days of timeline events and exports directly to a JSON file.
EXAMPLE 7
"2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" | Get-XdrEndpointDeviceTimeline
Retrieves timeline events using pipeline input.
PARAMETERS
-DeviceId
The unique identifier of the device. Accepts pipeline input and can also be specified as MachineId. Use this parameter set when identifying the device by ID.
Type: String
Parameter Sets: ByDeviceId
Aliases: MachineId, SenseMachineId
Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByPropertyName, ByValue)
Accept wildcard characters: False
-MachineDnsName
The DNS name of the machine. Use this parameter set when identifying the device by DNS name.
Type: String
Parameter Sets: ByMachineDnsName
Aliases:
Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-FromDate
The start date for the timeline. Defaults to 1 hour before current time.
Type: DateTime
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: ((Get-Date).AddHours(-1))
Accept pipeline input: False
Accept wildcard characters: False
-ToDate
The end date for the timeline. Defaults to current time.
Type: DateTime
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: (Get-Date)
Accept pipeline input: False
Accept wildcard characters: False
-LastNDays
Specifies the number of days to look back. Overrides FromDate and ToDate if specified.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-PageSize
The number of events to return per page. Defaults to 1000 for optimal performance.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 1000
Accept pipeline input: False
Accept wildcard characters: False
-MarkedEventsOnly
Only return events that have been marked in the timeline.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-SenseClientVersion
Optional. The version of the Sense client.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SkipIdentityEvents
Skip generating and including identity events. By default, identity events are included.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-SkipMdiOnlyEvents
Skip MDI-only events. By default, MDI-only events are supported.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-DoNotUseCache
Bypass the API cache when retrieving timeline data.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ForceUseCache
Force using the API cache when retrieving timeline data.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-IncludeSentinelEvents
Include Sentinel events in the timeline results.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-EventType
Filter events by type. Supports wildcards. Examples: 'Process*', 'Network*', 'File*'.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-EventsGroups
Filter events by group category. Accepts one or more of the following values: AlertsRelatedEvents, AntiVirus, AppGuard, AppControl, ExploitGuard, Files, Firewall, Network, Processes, Registry, ResponseActions, ScheduledTask, SmartScreen, Other, UserActivity. Multiple values can be specified to include multiple event groups.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-DataTypes
Filter events by data type. Accepts one or more of the following values: Events, Techniques. Multiple values can be specified to include multiple data types.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SourceProviders
Filter events by source provider. Accepts one or more of the following values: MDE, MDI. Multiple values can be specified to include multiple source providers.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ThrottleLimit
The maximum number of concurrent requests. Defaults to 10.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 10
Accept pipeline input: False
Accept wildcard characters: False
-TimeoutSeconds
Maximum time in seconds to wait for all requests to complete. Defaults to 3600 (1 hour).
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 3600
Accept pipeline input: False
Accept wildcard characters: False
-MaxRetries
Maximum number of retry attempts for failed API requests. Defaults to 10.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 10
Accept pipeline input: False
Accept wildcard characters: False
-RetryDelaySeconds
Base delay in seconds between retry attempts (uses exponential backoff). Defaults to 30.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 30
Accept pipeline input: False
Accept wildcard characters: False
-ChunkHours
The size of each time chunk in hours for parallel processing. Defaults to 4 hours. For time windows of 40 hours or less, chunk size is automatically calculated as totalHours/10. Larger chunks reduce overhead but may increase individual request times.
Type: Int32
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: 4
Accept pipeline input: False
Accept wildcard characters: False
-OutputPath
Optional. The path to store temporary JSON files. Defaults to a temp folder.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-KeepTempFiles
If specified, keeps the temporary JSON files after merging.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-AllowPartial
Returns completed chunks when one or more chunks fail or the request times out. By default, the cmdlet fails rather than returning incomplete timeline data.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ExportPath
Optional. Export results directly to a JSON file at the specified path.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
The ProgressAction parameter is a common parameter, not a cmdlet parameter. For more information, see about_CommonParameters.
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.