POWERSHELL COMMAND
Get-XdrEndpointDeviceTimeline
Retrieves the timeline of events for a specific device from Microsoft Defender XDR.
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.
Syntax
Get-XdrEndpointDeviceTimeline -DeviceId <string> [-FromDate <datetime>] [-ToDate <datetime>] [-LastNDays <int>] [-PageSize <int>] [-MarkedEventsOnly] [-SenseClientVersion <string>] [-SkipIdentityEvents] [-SkipMdiOnlyEvents] [-DoNotUseCache] [-ForceUseCache] [-IncludeSentinelEvents] [-EventType <string>] [-EventsGroups <string[]>] [-DataTypes <string[]>] [-SourceProviders <string[]>] [-ThrottleLimit <int>] [-TimeoutSeconds <int>] [-MaxRetries <int>] [-RetryDelaySeconds <int>] [-ChunkHours <int>] [-OutputPath <string>] [-KeepTempFiles] [-AllowPartial] [-ExportPath <string>] [<CommonParameters>]
Get-XdrEndpointDeviceTimeline -MachineDnsName <string> [-FromDate <datetime>] [-ToDate <datetime>] [-LastNDays <int>] [-PageSize <int>] [-MarkedEventsOnly] [-SenseClientVersion <string>] [-SkipIdentityEvents] [-SkipMdiOnlyEvents] [-DoNotUseCache] [-ForceUseCache] [-IncludeSentinelEvents] [-EventType <string>] [-EventsGroups <string[]>] [-DataTypes <string[]>] [-SourceProviders <string[]>] [-ThrottleLimit <int>] [-TimeoutSeconds <int>] [-MaxRetries <int>] [-RetryDelaySeconds <int>] [-ChunkHours <int>] [-OutputPath <string>] [-KeepTempFiles] [-AllowPartial] [-ExportPath <string>] [<CommonParameters>]
Parameters
-DeviceId
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | true (ByValue, ByPropertyName) |
| Default | Not documented |
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.
-MachineDnsName
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
The DNS name of the machine. Use this parameter set when identifying the device by DNS name.
-FromDate
| Property | Value |
|---|---|
| Type | DateTime |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | ((Get-Date).AddHours(-1)) |
The start date for the timeline. Defaults to 1 hour before current time.
-ToDate
| Property | Value |
|---|---|
| Type | DateTime |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | (Get-Date) |
The end date for the timeline. Defaults to current time.
-LastNDays
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 0 |
Specifies the number of days to look back. Overrides FromDate and ToDate if specified.
-PageSize
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 1000 |
The number of events to return per page. Defaults to 1000 for optimal performance.
-MarkedEventsOnly
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Only return events that have been marked in the timeline.
-SenseClientVersion
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Optional. The version of the Sense client.
-SkipIdentityEvents
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Skip generating and including identity events. By default, identity events are included.
-SkipMdiOnlyEvents
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Skip MDI-only events. By default, MDI-only events are supported.
-DoNotUseCache
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Bypass the API cache when retrieving timeline data.
-ForceUseCache
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Force using the API cache when retrieving timeline data.
-IncludeSentinelEvents
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
Include Sentinel events in the timeline results.
-EventType
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Filter events by type. Supports wildcards. Examples: ‘Process*’, ‘Network*’, ‘File*’.
-EventsGroups
| Property | Value |
|---|---|
| Type | String[] |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
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.
-DataTypes
| Property | Value |
|---|---|
| Type | String[] |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
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.
-SourceProviders
| Property | Value |
|---|---|
| Type | String[] |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
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.
-ThrottleLimit
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 10 |
The maximum number of concurrent requests. Defaults to 10.
-TimeoutSeconds
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 3600 |
Maximum time in seconds to wait for all requests to complete. Defaults to 3600 (1 hour).
-MaxRetries
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 10 |
Maximum number of retry attempts for failed API requests. Defaults to 10.
-RetryDelaySeconds
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 30 |
Base delay in seconds between retry attempts (uses exponential backoff). Defaults to 30.
-ChunkHours
| Property | Value |
|---|---|
| Type | Int32 |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | 4 |
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.
-OutputPath
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Optional. The path to store temporary JSON files. Defaults to a temp folder.
-KeepTempFiles
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
If specified, keeps the temporary JSON files after merging.
-AllowPartial
| Property | Value |
|---|---|
| Type | SwitchParameter |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | False |
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.
-ExportPath
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Optional. Export results directly to a JSON file at the specified path.
Examples
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2"
Retrieves the last hour of timeline events for the specified device.
Get-XdrEndpointDeviceTimeline -MachineDnsName "computer.contoso.com"
Retrieves the last hour of timeline events using the machine DNS name.
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" -FromDate (Get-Date).AddDays(-7) -ToDate (Get-Date)
Retrieves timeline events for the last 7 days using parallel requests.
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" -LastNDays 90 -ThrottleLimit 5
Retrieves 90 days of timeline events with 5 concurrent requests.
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" -EventType "Process*"
Retrieves timeline events filtered to process-related events only.
Get-XdrEndpointDeviceTimeline -DeviceId "2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" -LastNDays 7 -ExportPath "C:\Reports\timeline.json"
Retrieves 7 days of timeline events and exports directly to a JSON file.
"2bec169acc9def3ebd0bf8cdcbd9d16eb37e50e2" | Get-XdrEndpointDeviceTimeline
Retrieves timeline events using pipeline input.
Output
Type: System.Object[]