Get Events
LAST UPDATED: APRIL 7, 2025
Retrieves a list of filtered events, including fields specified by the user.
Implementation | Python |
Command Category | Basic Utility |
Tags | EVENT EVENT SEARCH |
Inputs
Parameter Name | Required/Optional | Description | Sample Data |
---|---|---|---|
Filter | Optional | The array of criteria, each containing one or more JSON object conditions, used to filter events.
|
JSON
|
Fields | Optional | The event fields to include in the response data. If no fields are specified, the default fields displayed are all those listed in the Sample Data, except for "Event Raw Data." | BEFORE VERSION 16.8
CODE
VERSION 16.8+
JSON
|
Start Time | Required | The start time (in UTC) for retrieving events. The time range is based on event intake time, rather than the time of occurrence. The API requires the input format to be yyyy-mm-dd HH:mm (e.g., 2024-08-22 00:00:00). | 2024-01-06 01:30:00 |
End Time | Required | The end time (in UTC) for retrieving events. The time range is based on event intake time, rather than the time of occurrence. The API requires the DateTime format to be yyyy-mm-dd HH:mm (e.g., 2024-08-22 00:00:00). | 2024-10-23 07:45:00 |
Output Format | Required | Allows users to choose the format in which to present event data. Available options are:
| 2 |
Page Index | Optional | The page number to view a subset of events. For example, if there exists 50 events, and the Page Size (the following parameter) is set to 49, and the Page Index is set to 1 (the second page), only one event will be displayed. The default page index is 0, indicating the first page.
| 0 |
Page Size | Optional | The maximum number of event records to fetch, ranging from 1 to 1000. For example, if there exists 50 events, and the Page Size is set to 49, and the Page Index (the previous parameter) is set to 1 (the second page), only one event will be displayed.
If the page size is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output. | 100 |
Sort Field | Optional | The field by which the results are sorted. Users can specify any field listed in the Fields parameter (e.g., | Event ID |
Sort Order | Optional | The order in which the results are sorted. This parameter is used in conjunction with Sort Field to control the sort behaviour. | Ascending |
Output
Remote Command API
The D3 command API allows you to send requests to D3 SOAR to execute this utility command via REST API.
Request
POST
https:/{base_url}/{api_namespace}/api/Command/GetEvents
Headers
Please refer to the page Webhook Configuration Guide - Authentication Method: API Keys for more details.
Request Body
{
"Username": <Username here>,
"Site": <Site here>,
"CommandParams": {
"Filter": [
[
{
"field": <Field 1 here>,
"operator": <Operator 1 here>,
"value": <Value 1 here>
},
{
"field": <Field 2 here>,
"operator": <Operator 2 here>,
"value": <Value 2 here>
}
],
[
{
"field": <Field 3 here>,
"operator": <Operator 3 here>,
"value": <Value 3 here>
}
]
],
"Fields": [
<Field Name 1 here>,
<Field Name 2 here>,
<Field Name 3 here>,
<Field Name 4 here>,
<Field Name 5 here>,
<Field Name 6 here>,
<Field Name 7 here>,
<Field Name 8 here>,
<Field Name 9 here>,
<Field Name 10 here>,
<Field Name 11 here>,
<Field Name 12 here>,
<Field Name 13 here>,
<Field Name 14 here>,
<Field Name 15 here>,
<Field Name 16 here>,
<Field Name 17 here>,
<Field Name 18 here>,
<Field Name 19 here>,
<Field Name 20 here>,
<Field Name 21 here>
],
"Start Time": <Start Time here>,
"End Time": <End Time here>,
"Output Format": <Output Format here>,
"Page Index": <Page Index here>,
"Page Size": <Page Size here>,
"Sort Field": <Sort Field here>,
"Sort Order": <Sort Order here>
}
}
Body Parameters
Parameter Name | Type | Required/Optional | Description |
---|---|---|---|
Username |
| Required | The username of the D3 SOAR user account making the request. |
Site |
| Required | The D3 SOAR site containing the desired events to retrieve with the request. |
Filter |
| Optional | The array of criteria, each containing one or more JSON object conditions, used to filter events.
|
Fields |
| Optional | The event fields to include in the response data. If no fields are specified, the default fields displayed are all those listed in the Sample Data, except for "Event Raw Data." |
Start Time |
| Required | The start time (in UTC) for retrieving events. The time range is based on event intake time, rather than the time of occurrence. The API requires the input format to be yyyy-mm-dd HH:mm (e.g., 2024-08-22 00:00:00). |
End Time |
| Required | The end time (in UTC) for retrieving events. The time range is based on event intake time, rather than the time of occurrence. The API requires the DateTime format to be yyyy-mm-dd HH:mm (e.g., 2024-08-22 00:00:00). |
Output Format |
| Required | Allows users to choose the format in which to present event data. Available options are:
|
Page Index |
| Optional | The page number to view a subset of events. For example, if there exists 50 events, and the Page Size (the following parameter) is set to 49, and the Page Index is set to 1 (the second page), only one event will be displayed. The default page index is 0, indicating the first page.
|
Page Size |
| Optional | The maximum number of event records to fetch, ranging from 1 to 1000. For example, if there exists 50 events, and the Page Size is set to 49, and the Page Index (the previous parameter) is set to 1 (the second page), only one event will be displayed.
If the page size is greater than zero, a "TotalPages" property will be displayed within the Key Fields tab in the output. |
Sort Field |
| Optional | The field by which the results are sorted. Users can specify any field listed in the Fields parameter (e.g., |
Sort Order |
| Optional | The order in which the results are sorted. This parameter is used in conjunction with Sort Field to control the sort behaviour. |
Sample Request
SAMPLE DATA BEFORE VERSION 16.8
{
"Username": "Admin",
"Site": "Security Operations",
"CommandParams": {
"Filter": [
[
{
"field": "Status",
"operator": "=",
"value": "Escalated"
},
{
"field": "IntakeTime",
"operator": ">=",
"value": "2020-09-25 23:20:03.693"
}
],
[
{
"field": "RiskLevel",
"operator": "=",
"value": "High"
}
]
],
"Fields": [
"ID",
"EventID",
"Type",
"Tactic",
"Technique",
"RiskLevel",
"TimeofOccurrence",
"IntakeTime",
"Status",
"Description",
"Site",
"Datasource",
"Eventsource",
"Username",
"Sourceip",
"Targetip",
"Integrationconnection",
"EventFileName",
"LastEscalatedBy",
"Event Raw Data",
"LinkedIncidents"
],
"Start Time": "2020-01-06 01:30:00",
"End Time": "2020-10-23 07:45:00",
"Output Format": 2,
"Page Index": 0,
"Page Size": 100
}
}
SAMPLE DATA FOR VERSION 16.8+
{
"Username":"Admin",
"Site":"Security Operations",
"CommandParams":{
"Filter":[
[
{
"field":"Data Source",
"operator":"=",
"value":"SentinelOne"
},
{
"field":"Status",
"operator":"=",
"value":"Open"
}
],
[
{
"field":"Data Source",
"operator":"=",
"value":"SentinelOne"
},
{
"field":"Status",
"operator":"=",
"value":"Escalated"
}
]
],
"Fields":[
"Event ID",
"Site",
"Tactic",
"Technique",
"Description",
"Time of Occurrence (UTC)",
"Intake Time (UTC)",
"Status",
"Data Source"
],
"Start Time":"2025-01-01 00:00:00",
"End Time":"2025-04-03 00:00:00",
"Output Format":2,
"Page Index":0,
"Page Size":2,
"Sort Field": "Event ID",
"Sort Order": "Descending"
}
}
Response
Response Fields
Field Name | Type | Description |
---|---|---|
error |
| The error message if the API request has failed. |
keyFields |
| The key fields from the API request. |
returnData |
| The return data from the API request. |
rawData |
| The raw data from the API request. |
outputData |
| The output data from the API request. |
Sample Response
BEFORE VERSION 16.8
{
"error": "",
"keyFields": {
"Pagination": {
"PageIndex": 0,
"PageSize": 100,
"TotalPages": 10
}
},
"returnData": "Successful",
"rawData": {
"events": [
{
"ID": "*****",
"EventID": 60075,
"Type": "DEVICE_PLUG",
"Tactic": "Defense Evasion",
"Technique": "Drive-by Compromise",
"RiskLevel": "High",
"TimeofOccurrence": null,
"IntakeTime": "2020-09-24 23:24:09.640",
"Status": "New",
"Description": null,
"Site": "APSOC",
"Datasource": "McAfee ePolicy Orchestrator",
"Eventsource": "Default Event Source",
"Username": null,
"Sourceip": null,
"Targetip": null,
"Integrationconnection": "Webhook",
"EventFileName": null,
"LastEscalatedBy": "admin user",
"Event Raw Data": {
"Body": {
"BodyType": 0
}
}
},
{
"ID": "*****",
"EventID": 60078,
"Type": "DEVICE_PLUG",
"Tactic": "Execution",
"Technique": "Timestomp",
"RiskLevel": "High",
"TimeofOccurrence": null,
"IntakeTime": "2020-09-25 23:20:03.693",
"Status": "Escalated",
"Description": null,
"Site": "APSOC",
"Datasource": "McAfee ePolicy Orchestrator",
"Eventsource": "Default Event Source",
"Username": null,
"Sourceip": null,
"Targetip": null,
"Integrationconnection": "Webhook",
"EventFileName": null,
"LastEscalatedBy": "admin user",
"Event Raw Data": {
"Body": {
"BodyType": 0
}
}
},
{
"ID": "*****",
"EventID": 60076,
"Type": "DEVICE_PLUG",
"Tactic": "Collection",
"Technique": "Data from Removable Media",
"RiskLevel": "High",
"TimeofOccurrence": null,
"IntakeTime": "2020-09-24 23:26:03.693",
"Status": "Dismissed",
"Description": null,
"Site": "APSOC",
"Datasource": "McAfee ePolicy Orchestrator",
"Eventsource": "Default Event Source",
"Username": null,
"Sourceip": null,
"Targetip": null,
"Integrationconnection": "Webhook",
"EventFileName": null,
"LastEscalatedBy": "admin user",
"Event Raw Data": {
"Body": {
"BodyType": 0
}
}
}
]
}
}
VERSION 16.8+
{
"events": [
{
"ID": "*****",
"Event ID": 60075,
"Event Type": "DEVICE_PLUG",
"Event Name": "Sample Name",
"Tactic": "Defense Evasion",
"Technique": "Drive-by Compromise",
"Risk Level": "High",
"Time of Occurrence": null,
"Intake Time": "2020-09-24 23:24:09.640",
"Status": "Open",
"Description": null,
"Site": "APSOC",
"Data Source": "McAfee ePolicy Orchestrator",
"Event Source": "Default Event Source",
"Username": null,
"Source IP": null,
"Target IP": null,
"Integration Connection": "Webhook",
"Uploaded Event File Name": null,
"Last Escalated By": "Admin User",
"Time of Event Escalation (UTC)": "2024-08-26 18:23:47.270",
"Time of Event Dismissal (UTC)": "",
"Linked Incidents": [
"20200924-5"
],
"Event Raw Data": {
"id": "*****=8",
"createdDateTime": "2021-06-01T17:48:19Z",
"lastModifiedDateTime": "2021-07-08T18:08:20Z",
"receivedDateTime": "2021-06-01T17:48:19Z",
"sentDateTime": "2021-06-01T17:47:55Z",
"hasAttachments": true,
"internetMessageId": "",
"subject": "Report Phishing",
"importance": "normal"
}
},
{
"ID": "*****",
"Event ID": 60078,
"Event Type": "DEVICE_PLUG",
"Event Name": "Sample Name",
"Tactic": "Execution",
"Technique": "Timestomp",
"Risk Level": "High",
"Time of Occurrence": null,
"Intake Time": "2020-09-25 23:20:03.693",
"Status": "Escalated",
"Description": null,
"Site": "APSOC",
"Data Source": "McAfee ePolicy Orchestrator",
"Event Source": "Default Event Source",
"Username": null,
"Source IP": null,
"Target IP": null,
"Integration Connection": "Webhook",
"Uploaded Event File Name": null,
"Last Escalated By": "Admin User",
"Time of Event Escalation (UTC)": "",
"Time of Event Dismissal (UTC)": "2024-08-26 18:23:47.270",
"Linked Incidents": [
"20200925-5"
],
"Event Raw Data": {
"id": "*****",
"createdDateTime": "2021-06-01T17:48:19Z",
"lastModifiedDateTime": "2021-07-08T18:08:20Z",
"receivedDateTime": "2021-06-01T17:48:19Z",
"sentDateTime": "2021-06-01T17:47:55Z",
"hasAttachments": true,
"internetMessageId": "",
"subject": "Report Phishing",
"importance": "normal"
}
},
{
"ID": "*****",
"Event ID": 60076,
"Event Type": "DEVICE_PLUG",
"Event Name": "Sample Name",
"Tactic": "Collection",
"Technique": "Data from Removable Media",
"Risk Level": "High",
"Time of Occurrence": null,
"Intake Time": "2020-09-24 23:26:03.693",
"Status": "Dismissed",
"Description": null,
"Site": "APSOC",
"Data Source": "McAfee ePolicy Orchestrator",
"Event Source": "Default Event Source",
"Username": null,
"Source IP": null,
"Target IP": null,
"Integration Connection": "Webhook",
"Uploaded Event File Name": null,
"Last Escalated By": "Admin User",
"Time of Event Escalation (UTC)": "2024-08-26 18:23:47.270",
"Time of Event Dismissal (UTC)": "",
"Linked Incidents": [
"20200924-1"
],
"Event Raw Data": {
"id": "*****",
"createdDateTime": "2021-06-01T17:48:19Z",
"lastModifiedDateTime": "2021-07-08T18:08:20Z",
"receivedDateTime": "2021-06-01T17:48:19Z",
"sentDateTime": "2021-06-01T17:47:55Z",
"hasAttachments": true,
"internetMessageId": "",
"subject": "Report Phishing",
"importance": "normal"
}
}
]
}