Skip to main content
Skip table of contents

Get Incidents‎

POST /Command/GetIncidents

Gets a list of filtered incidents with specified fields.

Request

Authentication: API keys or JSON web tokens (JWT)

Body Parameters

Parameter Name

Type

Required/Optional

Description

Username

string

Required

The username of the D3 SOAR user account making the request.

Site

string

Required

The D3 SOAR site containing the desired incidents to retrieve with the request.

Filter

array<array<JSON Object>>

Optional

The filter serve to filter data. The "field" key indicates the selected field in the incident, the "operator" key signifies the condition operator applied to the field, and the "value" key represents the desired value. The "section" key is optional; however, if a "section" key is added, it will be treated as a dynamic field for filtering. "AND" logic applies between JSON objects in the same array, "OR" logic applies between different arrays. Valid values for the "field" key as a non-dynamic field are every valid key in the "Static Fields" section except "Incident Raw Data". (Input must be in JSON format)

Available operators: ["<",">","=","<=",">=","!=","LIKE","IS EMPTY","IS NOT EMPTY"]

Static Fields

array<string>

Optional

Select the static incident field keys to be displayed in the result. The keys available for selection are listed below. In the case of an empty input, only general keys will be selected for each resulting incident.

General keys are every key in the list below except for "Date Closed", "Closed by", "Incident Raw Data", and "Custom Field".

The "Playbook" field returns playbooks that have either been completed or stopped on error.

Note: "Date Created", "Date Modified", and "Date Closed" is in UTC time. Input must be in JSON format.

Dynamic Fields

JSON Object

Optional

Select the dynamic incident fields to be displayed in the result. The key in the JSON object is the dynamic field section name. The value array contains the names of the elements under the section. Input must be in JSON format.

Start Time

string

Required

The start of the date range for incidents. Based on 'Date Created' (UTC) of the incident.

End Time

string

Required

The end of the date range for incidents. Based on 'Date Created' (UTC) of the incident.

Output Format

integer

Optional

1 - CSV, 2 - JSON, 3 - CSV link, 4 - JSON link.

Page Index

integer

Optional

The page number to receive results from. The default page index is 0.

In the case of extensive datasets, the total pages within the key fields section will be shown as "N/A."

Note: if no value or 0 is given for both Page Index and Page Size, all incidents will be fetched. If pagination index is provided, total pages will show in key fields outputs.

Page Size

integer

Optional

The maximum number of incidents to fetch, ranges from 1 to 1000. If no value or 0 is given, a default page size of 100 will be applied.

In the case of extensive datasets, the total pages within the key fields section will be shown as "N/A."

Note: if no value or 0 is given for both Page Index and Page Size, all incidents will be fetched. If pagination size is provided, total pages will show in key fields outputs.

READER NOTE

Static Fields represents an input parameter as an array of strings. Each field in this array is optional. If you include these fields, the response will contain the specified fields. The fields are:

IR Number, IR Type, Title, Status, Severity, Stage, Priority, Disposition, Tags, Owner, Creator, Timezone, Date Created, Date Modified, Playbook, Description, Conclusion, Investigation Team, Linked Incidents, Incident Raw Data, Event Raw Data

READER NOTE

The fields Incident Raw Data and Event Raw Data can contain large amounts of data. Use these fields cautiously and consider using pagination input parameters (page index and page number) to manage the data volume efficiently.

READER NOTE

For Date/Time parameters Start Time and End Time, all times and timestamps must follow the format: yyyy-mm-dd hh:mm:ss.

  • e.g. May 15, 2024, 2:32 PM should be written as 2024-05-15 14:32:00.

Body Sample Data

application/json
JSON
{
  "Username": "Admin",
  "Site": "Security Operations",
  "CommandParams": {
    "Filter": [
      [
        {
          "field": "Status",
          "operator": "!=",
          "value": "Open"
        },
        {
          "field": "Severity",
          "operator": "=",
          "value": "High"
        }
      ],
      [
        {
          "section": "Customer",
          "field": "Name",
          "operator": "LIKE",
          "value": "VIP%"
        }
      ]
    ],
    "Static Fields": [
      "IR Number",
      "IR Type",
      "Title",
      "Status",
      "Severity",
      "Stage",
      "Priority",
      "Disposition",
      "Tags",
      "Owner",
      "Creator",
      "Timezone",
      "Date Created",
      "Date Modified",
      "Playbook",
      "Description",
      "Conclusion",
      "Investigation Team",
      "Linked Incidents",
      "Incident Raw Data",
      "Event Raw Data"
    ],
    "Dynamic Fields": {
      "Incident Owner": [
        "Owner Last Update Time",
        "Time Spend"
      ],
      "Customer": [
        "Name",
        "Country"
      ]
    },
    "Start Time": "2019-03-26 00:00:00",
    "End Time": "2021-12-31 10:15:00",
    "Output Format": 2,
    "Page Index": 0,
    "Page Size": 100
  }
}

Response

200 OK

application/json

Response Fields

Field Name

Type

Description

error

string

The error message if the API request has failed.

keyFields

JSON Object

The key fields from the API request.

returnData

string

The return data from the API request.

rawData

JSON Object

The raw data from the API request.

Sample Data

CODE
{
    "error": "",
    "keyFields": {
        "Pagination": {
            "PageIndex": 0,
            "PageSize": 100,
            "TotalPages": 10
        }
    },
    "returnData": "Successful",
    "rawData": {
        "incidents": [
            {
                "Incident No.": "20211222-3",
                "Incident Type": "Playbook - DLP",
                "Title": "222222222",
                "Status": "Open",
                "Severity": "Low",
                "Stage": "Data Aggregation Stage",
                "Priority": "1 - Medium",
                "Disposition": "",
                "Tags": "",
                "Owner": "Admin User",
                "Creator": "admin",
                "Closed by": "System User",
                "Time Zone": "PST",
                "Date Created": "2019-04-08 09:17:32",
                "Date Modified": "2019-04-09 11:31:30",
                "Date Closed": "2019-05-14 13:46:00",
                "Playbook": "Endpoint Protection - Unauthorized Access",
                "Description": "",
                "Conclusion": "",
                "Investigation Team": "",
                "Linked Incidents": "20211223-20",
                "Incident Raw Data": "",
                "Customer - Name": "VIP_Mary",
                "Customer - Country": "France",
                "Incident Owner - Owner Last Update Time": null,
                "Incident Owner - Time Spend": null,
                "Custom Field": "",
                "Event Raw Data": ""
            },
            {
                "Incident No.": "20211222-4",
                "Incident Type": "Playbook - DLP",
                "Title": "",
                "Status": "Open",
                "Severity": "Low",
                "Stage": "Data Aggregation Stage",
                "Priority": "1 - Medium",
                "Disposition": "",
                "Tags": "",
                "Owner": "Admin User",
                "Creator": "admin",
                "Closed by": "System User",
                "Time Zone": "PST",
                "Date Created": "2021-12-22 15:14:26",
                "Date Modified": "2021-12-22 15:51:56",
                "Date Closed": "2021-12-24 16:15:14",
                "Playbook": "Endpoint Protection - Unauthorized Access",
                "Description": "",
                "Conclusion": "",
                "Investigation Team": "",
                "Linked Incidents": "20211225-1,20211225-2",
                "Incident Raw Data": {
                  "source": "Automation",
                  "title": "Incident Generated For Get Incidents Utility Command Test (2024-08-02 22:02:59)",
                  "description": "This is an incident generated for Utility Command Test"
                },
                "Incident Raw Data": {
                    "source": "Automation",
                    "title": "Incident Generated for Search Incident Utility Command Test (2024-08-02 22:02:59)",
                    "description": "This is an incident generated for Utility Command Test"
                },
                "Customer - Name": "VIP_Robert",
                "Customer - Country": "Canada",
                "Incident Owner - Owner Last Update Time": null,
                "Incident Owner - Time Spend": null,
                "Custom Field": "",
                "Event Raw Data": ""
            }
        ]
    }
}

400 BadRequest

application/json

Response Fields

Field Name

Type

Description

Error

string

A error message when the API request fails.

Sample Data

JSON
{"Error": "The body of the request must be a valid JSON object"}

401 Unauthorized

application/json

Response Fields

Field Name

Type

Description

Error

string

A error message when the API request fails.

Sample Data

JSON
{"Error": "Invalid authentication key."}

429 TooManyRequests

application/json

Response Fields

Field Name

Type

Description

Error

string

A error message when the API request fails.

Sample Data

JSON
{"Error": "The request exceeds rate limits or is otherwise blocked by rate limiting policies."}

500 InternalServerError

application/json

Response Fields

Field Name

Type

Description

Error

string

A error message when the API request fails.

Sample Data

JSON
{"Error": "Unexpected Error."}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.