Rapid7 InsightIDR V2

LAST UPDATED: SEPTEMBER 18, 2025

Overview

Rapid7's InsightIDR is a security center for incident detection and response, authentication monitoring, and endpoint visibility. InsightIDR identifies unauthorized access from external and internal threats and highlights suspicious activity so users do not have to weed through thousands of data streams.

D3 SOAR is providing REST operations to function with Rapid7 InsightIDR.

Rapid7 InsightIDR is available for use in:

D3 SOAR	V16.1+
Category	SIEM & XDR
Deployment Options	Option II, Option IV

Connection

To connect to Rapid7 InsightIDR from D3 SOAR, follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The API base URL excluding the trailing /idr. Refer to Supported regions for the appropriate InsightIDR base URL.	https://ca.api.insight.rapid7.com
API Key	The API Key obtained from the Rapid7 Insight platform.	*****
API Version	The API version used for the connection.	v1

Permission Requirements

Each endpoint in the Rapid7 InsightIDR V2 API requires a certain permission scope. The following are required scopes for the commands in this integration:

Command	Required Permissions
Command	Built-in Role	Permissions
Assign Investigations	InsightIDR Analyst	InsightIDR Core > View and Change
Close Investigation
Create Comments
Fetch Event	InsightIDR Viewer Log Search View Only	InsightIDR Core > View Only Log Management and Querying > View Only
Fetch Event	Must be an MDR customer with access to the Alerts experience to return alert-related information. Contact Rapid7 for more information.
Fetch Incident	InsightIDR Viewer	InsightIDR Core > View Only
Get Alert Available Assignees	InsightIDR Viewer Must be an MDR customer with access to the Alerts experience. Contact Rapid7 for more information.	Collector > View Only Must be an MDR customer with access to the Alerts experience. Contact Rapid7 for more information.
Get Alert Evidences
Get Detection Rules	InsightIDR Viewer	InsightIDR Core > View Only
Get Investigation Evidence	Requires the restricted API. Contact Rapid7 for more information.
List Alert Fields	InsightIDR Viewer	Collector > View Only
List Alert Fields	Must be an MDR customer with access to the Alerts experience. Contact Rapid7 for more information.
List Attachments	InsightIDR Viewer	Collector > View Only
List Investigation		InsightIDR Core > View Only
List Investigation Comments		Collector > View Only
List Logs	Log Search View Only	Log Management and Querying > View Only
Search Alerts	InsightIDR Viewer	Collector > View Only
Search Alerts	Must be an MDR customer with access to the Alerts experience. Contact Rapid7 for more information.
Search Logs	Log Search View Only	Log Management and Querying > View Only
Search Users	InsightIDR Viewer	Collector > View Only
Set Investigation Status	InsightIDR Analyst	InsightIDR Core > View and Change
Update Alerts	InsightIDR Viewer	Collector > View Only
Update Alerts	Must be an MDR customer with access to the Alerts experience. Contact Rapid7 for more information.
Update Investigations	InsightIDR Analyst	InsightIDR Core > View and Change
Test Connection	InsightIDR Viewer	InsightIDR Core > View Only

As Rapid7 InsightIDR V2 is using role-based access control (RBAC), the API Key is generated (and updated) based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the Rapid7 InsightIDR V2 console for each command in this integration.

Configuring Rapid7 InsightIDR to Work with D3 SOAR

An InsightIDR account with an assigned role is required to run integration commands. A Platform Administrator must create the account and assign the appropriate privileges. After the account is created, the user can activate it and generate their own API key.

READER NOTE

Only Platform Administrators have access to user management.
Platform Administrators have no product access by default. To grant full administrative rights to a Rapid 7 product (i.e., InsightIDR), Platform Administrators should assign themselves the Admin roles for each product.

For more information on user roles and their access levels, refer to User Roles.

Adding a User and Configuring Their Role

This section guides Platform Administrators in creating a new user and assigning a role, enabling the user to run integration commands as needed.

Log in to the Rapid7 Insight platform as a Platform Administrator.
Navigate to Administration > User Management > Users, then click the Create New User button.
Configure the user profile.
1. Enter the email address.
2. Enter the first name.
3. Enter the last name.
4. (Optional) Select this option to make this user a Platform Administrator.
5. Click the Create User button.
After the profile has been configured, the new user will receive an activation email.
Scroll down to the Individual Privileges section and click the Assign Individual Privileges button.
Users can alternatively assign group privileges to apply roles to an entire group.
Select the InsightIDR product, add the necessary roles, then click the Save Individual Privileges button.

Creating a Custom Role

To create custom roles, follow the steps below.

Navigate to Administration > User Management > Roles, then click the Create New Role button.
Enter a name for the role, then select the insightIDR product.
Configure the permissions as necessary and save.

Generating the API Key

This section demonstrates how the newly created user can generate an API key.

Navigate to Administration > API Key Management > User Keys, then click the Generate New User Key button.
Generate a new API key.
1. Select the organization.
2. Enter the name for the key.
3. Click the Submit button.
Click the Copy button to save the API key to the clipboard. Refer to sub-step 2 under step 3i of Configuring D3 SOAR to Work with Rapid7 InsightIDR.
The key cannot be retrieved again after navigating away from this pop-up.

Configuring D3 SOAR to Work with Rapid7 InsightIDR

Log in to D3 SOAR.
Find the Rapid7 InsightIDR integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Rapid7 InsightIDR V2 in the search box to find the integration, then click it to select it.
4. Click on the + Connection button on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Rapid7 InsightIDR.
1. Connection Name: The desired name for the connection.
2. Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
4. Agent Name (Optional): The proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): The description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: The checkbox that enables the connection to be used when selected.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the Server URL. The default value is https://us2.idr.nsight.rapid7.com.
  2. Input the API Key from the Rapid7 InsightIDR platform. Refer to step 3 of Generating the API Key.
  3. Input the API Version. The default value is v1.
10. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
11. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
Test the connection.
1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Rapid7 InsightIDR includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Rapid7 InsightIDR API, refer to the following resources:

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Rapid7 InsightIDR V2 to Work with D3 SOAR sections for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose the desired date and time format, then click on the Save button.

The selected time format will now be visible when configuring Date/Time command input parameters.

Assign Investigations

Assigns a user to the specified investigations using their IDs or RRNs. The user must be a platform administrator, a product administrator, or a read/write user with access to either InsightIDR or InsightUBA.

READER NOTE

Investigation IDs or RRNs is a required parameter to run this command.

Run the List Investigations command to obtain the Investigation IDs or RRNs. Investigation IDs or RRNs can be found in the raw data at the path $.data[*].id or $.data[*].rrn.

Input

Input Parameter

Required/Optional

Description

Example

Investigation IDs or RRNs

Required

The investigation IDs or RRNs used to assign the investigations.

For API v1, use either Investigation IDs or RRNs.
For API v2, use RRNs only.

Investigation IDs or RRNs can be obtained using the List Investigations command.

JSON

[
  "rrn:*****T2A4"
]

User Email Address

Required

The email address of the user to assign to the investigations. This is the email address associated with the assigned user’s Insight Platform account.

user@example.com

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Assign Investigations failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: User not found, cannot be assigned to investigation.

Error Sample Data

Assign Investigations failed.

Status Code: 404.

Message: User not found, cannot be assigned to investigation.

Close Investigation

Sets the "closed" status on investigations using the given IDs. If the investigations already have the specified status, then no changes will be made and the investigations will be returned.

READER NOTE

Investigation IDs or RRNs is a required parameter to run this command.

Run the List Investigations command to obtain the Investigation IDs or RRNs. Investigation IDs or RRNs can be found in the raw data at the path $.data[*].id or $.data[*].rrn.

Input

Input Parameter

Required/Optional

Description

Example

Investigation IDs or RRNs

Required

The investigation IDs or RRNs used to close the investigations.

For API v1, use either Investigation IDs or RRNs.
For API v2, use RRNs only.

Investigation IDs or RRNs can be obtained using the List Investigations command.

JSON

[
  "rrn:*****T2A4"
]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Close Investigation failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: A server error occurred.

Error Sample Data

Close Investigation failed.

Status Code: 500.

Message: A server error occurred.

Create Comments

Creates comments for a particular target. The target determines where the comment will appear within InsightIDR. Only certain types of RRNs are permitted as targets, such as investigation RRNs.

READER NOTE

Target RRNs is a required parameter to run this command.

Run Fetch Incident or List Investigations command to obtain the Investigation RRNs. Investigation RRNs can be found in the raw data at the path $.data[*].rrn in both cases.

File ID and File Source

It is not recommended to use the Test Command feature with the Create Comments command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

Input

Input Parameter	Required/Optional	Description	Example
Target RRNs	Required	The RRNs of the targets to add a comment. To add a comment to an investigation, investigation RRNs are required. Investigation RRNs can be obtained using the Fetch Incident or List Investigations command.	JSON `[ "rrn:*****T2A4" ]`
Comment Body	Optional	The body of the comment.	Hello World. 0817a
File IDs	Optional	The file IDs of the files to attach to the comment.	JSON `[ "*****" ]`
File Source	Optional	The file source of the files to attach. The options for file source are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event By default, the value is set to IR Attachment.	IR Attachment

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Create Comments failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: A server error occurred.

Error Sample Data

Create Comments failed.

Status Code: 500.

Message: A server error occurred.

Fetch Event

Searches for events from Rapid7 InsightIDR. Both investigations and logs can be fetched as events.

READER NOTE

Search Condition is an optional parameter to run this command.

Run the List Logs command to obtain the Log IDs. Log IDs can be found in the raw data at the path $.logs[*].id.

For this command, Context Data is only available for the Log Search event type.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start of the time range (in UTC) to fetch for events.	2020-07-27 01:10:10
End Time	Required	The end of the time range (in UTC) to fetch for events.	2020-07-28 23:59:59
Number of Event(s) Fetched	Optional	The number of the most recent events to fetch. Acceptable values are between 1 and 100. By default, all events matching the filter parameters will be returned.	50
Search Condition	Optional	Filters the search results using queries. This parameter only applies to the Log Search Event Type. Log IDs are required to build the Search Condition. Log IDs can be obtained using the List Logs command.	logid=*****
Investigation Statuses	Optional	Filters investigations by status. This parameter only applies to the Investigation event type. Available options are: Open Closed Investigation Open and Investigation By default, all investigations regardless of their status are returned.	Open and Investigating
Event Type	Optional	The type of events to fetch. Available options are: Log Search Investigation By default, the value is set to Log Search.	investigation
Investigation Priority	Optional	Filters investigations by priority. This parameter only applies to the Investigation event type. Available options are: Critical High Medium Low Unspecified By default, all investigations regardless of their priority are returned.	Critical

Output

To view the sample output data for all commands, refer to this article.

Fetch Event Field Mapping

See Field Mappings.

The Rapid7 InsightIDR system integration includes pre-configured field mappings for the default event source.

The Default Event Source is the default system-provided set of field mappings applied when the fetch event command is executed. It includes a Main Event JSON Path, which is the JSONPath expression that points to the base array of event objects. The source field path continues from this array to locate the required data.

The Main Event JSON Path can be viewed by clicking on the Edit Main JSON Path button.

Main Event JSON Path: $.data
The root array contains the event objects. Within each object, the key sequence_number denotes the Unique Event Key field. As such, the full JSONPath expression to extract the Unique Event Key is $.data.sequence_number.
Event Source for Investigation
The D3 system configures the field mappings which are specific to the investigation-related events (e.g., Document ID and Rule RRN). If a source field in the field mapping is not found, the corresponding field mapping will be ignored. Because the eventType field in the raw data for investigations consistently has the value investigation, these events can be identified by the Search String: {$.eventType}=investigation. Click Edit Event Source to view the Search String.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Default (Main Event JSON Path: $.data)
Unique Event Key	.sequence_number
Start Time	.kvp_info[?(@.key.text=='json.timestamp')].value.text
Source IP address	.kvp_info[?(@.key.text=='json.source_address')].value.text
Source Port	.kvp_info[?(@.key.text=='json.source_port')].value.text
Destination IP address	.kvp_info[?(@.key.text=='json.destination_address')].value.text
Destination Port	.kvp_info[?(@.key.text=='json.destination_port')].value.text
API Transport Protocol	.kvp_info[?(@.key.text=='json.transport_protocol')].value.text
Service Status	.kvp_info[?(@.key.text=='json.connection_status')].value.text
Original Event ID	.kvp_info[?(@.key.text=='json.community_id')].value.text
Bytes In	.kvp_info[?(@.key.text=='json.incoming_bytes')].value.text
Bytes Out	.kvp_info[?(@.key.text=='json.outgoing_bytes')].value.text
Source Username	.kvp_info[?(@.key.text=='json.user')].value.text
Severity	.kvp_info[?(@.key.text=='json.severity_name')].value.text
Description	.kvp_info[?(@.key.text=='json.description')].value.text
Event Source for Investigations (Search String: {$.eventType}=investigation) The search string format is {JSON path}=value. If the value of the eventType key is investigation in the event object under raw data, then the Investigation-related events will use the field mapping below.
Document ID	.rrn
Start Time	.created_time
Source	.source
Title	.title
Description	.alerts[*].type_description
Status	.status
Disposition	.disposition
Investigation RRN	.rrn
Alert Type	.alerts[*].type
Alert Name	.alertDetails[*].title
Alert Source	.alertDetails[*].alert_source
Alert Timestamp	.alertDetails[*].created_time
Alert ID	.alertDetails[*].id
Rule Name	.alertDetails[*].detection_rule_rrn.rule_name
Rule RRN	.alertDetails[*].detection_rule_rrn.rule_rrn
Sub Event	.alertDetails

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Search Condition parameter is required for this command.

Error Sample Data

Fetch Event failed.

Status Code: 400.

Message: Search Condition parameter is required for this command.

Fetch Incident

Searches for investigations as incidents from Rapid7 InsightIDR.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start of the time range (in UTC) to fetch for incidents (in UTC).	2020-07-27 01:10:10
End Time	Required	The end of the time range (in UTC) to fetch for incidents (in UTC).	2020-07-28 23:59:59
Number of Incident(s) Fetched	Optional	The number of the most recent incidents to fetch. Acceptable values are between 1 and 100. If the value is unspecified or outside of the range of acceptable values, then all incidents matching the filter conditions will be returned.	50
Investigation Statuses	Optional	Filters the results by investigation status. Available options are: Open Closed Investigating Open and Investigating By default, all incidents regardless of their status are returned.	Open and Investigating
Ingest Investigation Evidence	Optional	The option to ingest the investigation evidence when set to True. Accessing investigation evidence requires the restricted InsightIDR API. Contact Rapid7 to request access. By default, the option is set to False.	True
Investigation Priority	Optional	Filters the results by investigation priority. Available options are: Critical High Medium Low Unspecified By default, all incidents regardless of their priority are returned.	Critical

Output

To view the sample output data for all commands, refer to this article.

Incident Field Mapping

For this integration, the default incident fields in D3 SOAR contain built-in source fields.

Event and Incident Intake Field Mapping

See Field Mappings.

Incident field mapping is required.

Incident Main JSON Path: $.data

The pre-configured field mappings are detailed below:

Field Name	Source Field
Title	.title
Description	.alerts[*].type_description
Severity	User-defined.
Incident Type *	User-defined
Incident Creator	User-defined
Incident Owner	User-defined
Investigation Playbook	User-defined
Due In Date	User-defined
Origin ID	User-defined
Unique Key	.rrn
Tactics	User-defined
Techniques	User-defined

Event Field Mapping

Main Event JSON Path: $.alertDetails

Refer to the table below for Event Field Mapping:

Field Name	Source Field
Event Source for Investigation Alerts (Search String: {$.eventType}=investigationAlerts) The search string format is {$.<field>}=<field value>. If the value of the eventType key is investigationAlerts in the event object under raw data, then the investigation-alert-related events will use the field mapping below.
Document ID	.id
Start Time	.created_time
Source	.alert_source
Title	.title
Description	.alert_type_description
Rule RRN	.detection_rule_rrn.rule_rrn
Rule Name	.detection_rule_rrn.rule_name
Alert Type	.alert_type
First Event Time	.first_event_time
Latest Event Time	.latest_event_time

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Incident failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The provided API Key is not authorized to perform the requested operation. Please check the permissions associated with the key. If the problem persists, contact Rapid7 support with the correlation Id from the response.

Error Sample Data

Fetch Incident failed.

Status Code: 403.

Message: The provided API Key is not authorized to perform the requested operation. Please check the permissions associated with the key. If the problem persists, contact Rapid7 support with the correlation Id from the response..

Get Alert Available Assignees

Retrieves users eligible for assignment to the specified alert.

READER NOTE

Alert RRN is a required parameter to run this command.

Run the Search Alerts or the Fetch Event command with Event Type set to Investigation to obtain the Alert RRN. Alert RRNs can be found in the raw data at the paths:
- $.data[*].rrn for Fetch Event
- $.alerts[*].rrn or $.rrns for Search Alerts

Input

Input Parameter	Required/Optional	Description	Example
Alert RRN	Required	The RRN of the alert used to retrieve available assignees. Alert RRN can be obtained using the Search Alerts or Fetch Event command, with Event Type set to Investigation.	rrn:alerts:ca:f424*****775a

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Alert Available Assignees failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized.

Error Sample Data

Get Alert Available Assignees failed.

Status Code: 401.

Message: Unauthorized.

Get Alert Evidence

Retrieves evidence associated with a specified alert.

READER NOTE

Alert RRN is a required parameter to run this command.

Run the Search Alerts or the Fetch Event command with Event Type set to Investigation to obtain the Alert RRN. Alert RRNs can be found in the raw data at the paths:
- $.data[*].rrn for Fetch Event
- $.alerts[*].rrn or $.rrns for Search Alerts

Input

Input Parameter	Required/Optional	Description	Example
Alert RRN	Required	The RRN of the alert for which to retrieve evidence. Alert RRNs can be obtained using the Search Alerts or Fetch Event command, with Event Type set to Investigation.	rrn:alerts:ca:***:alert:1:***

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Alert Evidence failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Not Found.

Error Sample Data

Get Alert Evidence failed.

Status Code: 404.

Message: Not Found.

Get Detection Rules

Retrieves information on Detection Rules or Custom Detection Rules.

READER NOTE

Rule RRNs is a required parameter to run this command.

Run the Fetch Event command to obtain the Rule RRNs. Rule RRNs can be found in the raw data at the path $.data[*].alertDetails[*].detection_rule_rrn.rule_rrn.

Input

Input Parameter	Required/Optional	Description	Example
Rule RRNs	Required	The RRNs of the Detection Rules or Custom Detection Rules for which to retrieve information. Rule RRNs can be obtained using the Fetch Event command at *$.data[].alertDetails[].detection_rule_rrn.rule_rrn*, with Event Type set to Investigation.	JSON `[ "rrn:cba:::detection-rule:*****" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Detection Rules failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: No results found with the provided RRN. Please ensure the RRN is correct and corresponds to an existing entity.

Error Sample Data

Get Detection Rules failed.

Status Code: 404.

Message: No results found with the provided RRN. Please ensure the RRN is correct and corresponds to an existing entity.

Get Investigation Evidence

Retrieves evidence associated with the specified investigation. Access to the restricted InsightIDR API is required. Contact Rapid7 to obtain access.

READER NOTE

This command requires the restricted InsightIDR API, which is not publicly available. Contact Rapid7 for access.
Investigation RRN is a required parameter to run this command.
- Run the List Investigations command to obtain the Investigation RRN. Investigation RRNs can be found in the raw data at $.data[*].rrn.

Input

Input Parameter	Required/Optional	Description	Example
Investigation RRN	Required	The RRN of the investigation for which to retrieve evidence. Investigation RRNs can be obtained using the List Investigation or Fetch Event command, with Event Type set to Investigation.	rrn:investigation:ca:f424*****DIBE

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Investigation Evidence failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Please check the documentation at https:insight.help.rapid7.com/docs/product-apis or contact the Rapid7 Support.

Error Sample Data

Get Investigation Evidence failed.

Status Code: 404.

Message: Please check the documentation at https:insight.help.rapid7.com/docs/product-apis or contact the Rapid7 Support.

List Alert Fields

Retrieves all supported alert fields.

Input

Input Parameter	Required/Optional	Description	Example
Path	Optional	Limits results to only fields that are the same as or less than this value. This value must be a node in the field's hierarchy, based on period (.) separators.	process
Search Term	Optional	Limits the results to those containing the search term. The search is case-insensitive.	priority
Limit	Optional	The maximum number of fields to return. Available values are integers between 1 and 10000. By default, the value is 100. To return all fields, enter -1.	10

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Alert Fields failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized.

Error Sample Data

List Alert Fields failed.

Status Code: 401.

Message: Unauthorized.

List Attachments

Retrieves attachments matching the specified request parameters. For example, this command can list all attachments of an investigation.

READER NOTE

Target RRNs is a required parameter to run this command.

Run the Fetch Incident or List Investigations command to obtain the Investigation RRNs. Investigation RRNs can be found in the raw data at the path $.data[*].rrn.

Input

Input Parameter

Required/Optional

Description

Example

Target RRN

Required

The RRN of the target object to which the attachment files are linked. To retrieve attachments of an investigation, investigation RRNs can be obtained using the Fetch Incident or List Investigations command. By default, all attachments are returned.

rrn*****55GJ

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Attachments failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid target RRN: *****.

Error Sample Data

List Attachments failed.

Status Code: 400.

Message: Invalid target RRN: *****.

List Investigations

Retrieves a page of investigations matching the specified request parameters. The investigations will be sorted by their created_time in descending order.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	Only investigations with a created_time after this date will be returned by the API. By default, investigations with any created_time may be returned	2020-05-09 09:27:11
End Time	Optional	Only investigations with a created_time before this date will be returned by the API. By default, investigations with any created_time may be returned	2020-07-09 09:27:11

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Investigations failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The provided API Key is not authorized to perform the requested operation. Please check the permissions associated with the key. If the problem persists, contact Rapid7 support with the correlation Id from the response.

Error Sample Data

List Investigations failed.

Status Code: 403.

Message: The provided API Key is not authorized to perform the requested operation. Please check the permissions associated with the key. If the problem persists, contact Rapid7 support with the correlation Id from the response.

List Investigations Comments

Retrieves all comments from the specified investigation.

READER NOTE

Investigation RRN is a required parameter to run this command.

Run the Fetch Incident or List Investigations command to obtain the Investigation RRN. Investigation RRNs can be found in the raw data at the path $.data[*].rrn for List Investigations.

Input

Input Parameter	Required/Optional	Description	Example
Investigation RRN	Required	The investigation RRN used to retrieve all associated comments. Investigation RRNs can be obtained using the Fetch Incident or List Investigations command. By default, all investigation comments are returned.	targ*****3210

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Investigations Comments failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Invalid target RRN: *****.

Error Sample Data

List Investigations Comments failed.

Status Code: 400.

Message: Invalid target RRN: *****.

List Logs

Retrieves all logs.

Input

N/A

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Logs failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Forbidden.

Error Sample Data

List Logs failed.

Status Code: 403.

Message: Forbidden.

Search Alerts

Returns alerts matching the search criteria. Use the List Alert Fields command for supported search parameters When more than 100 alerts are found, then only the first 100 alerts will return details while the remaining will simply return Alert RRNs.

READER NOTE

Search Terms is an optional parameter to run this command.

Run the List Alert Fields command to obtain the Field IDs. Field IDs can be found in the raw data at the path $.fields[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Optional	The start of the time range to search for alerts. By default, the Start Time is 7 days before the End Time.	2023-10-24 14:15:22
End Time	Optional	The end of the time range to search for alerts. By default, the End Time is the current time.	2023-10-25 14:15:22
Search Terms	Optional	The terms used for matching in the search. Alert Field IDs are required to use this parameter. Field IDs can be obtained using the List Alert Fields command. Refer to Search Alerts for more information.	JSON `[ { "field_ids": [ "process.cmd_line" ], "operator": "EQUALS", "terms": [ "powershell.exe" ] } ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search Alerts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized.

Error Sample Data

Search Alerts failed.

Status Code: 401.

Message: Unauthorized.

Search Logs

Searches the logs specified by Log IDs with the provided query.

READER NOTE

Log IDs is a required parameter to run this command.

Run the List Logs command to obtain the Log IDs. Log IDs can be found in the raw data at the path $.logs[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Log IDs	Required	The IDs of the logs that the query is run against. Log IDs can be obtained using the List Logs command.	JSON `[ "*****" ]`
Query Statement	Optional	The LEQL query used to run against the logs. Refer to Components for Building a Query \| Rapid7 InsightIDR for information on building a query.	where(service_info.assigned_user = 'user1')
Start Time	Optional	The start of the time range for the query. By default, Start Time is 20 minutes before End Time.	2024-05-20 00:00:00
End Time	Optional	The end of the time range for the query. By default, End Time is the current time.	2024-05-20 01:00:00
Time Range	Optional	The relative time range. Acceptable values are: yesterday today last 1 week last 3 days If this parameter is specified, Start Time and End Time will be omitted.	last 3 days

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search Logs failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Not found.

Error Sample Data

Search Logs failed.

Status Code: 404.

Message: Not found.

Search Users

Searches for InsightIDR “Users and Accounts” entities (not Insight Platform users) that match the specified criteria. Results are returned in alphabetical order. For more information, refer to Users and Accounts.

Input

Input Parameter	Required/Optional	Description	Example
Names	Optional	The names of the users to search.	JSON `[ "John Doe" ]`
Domain	Optional	The domain in which to search users.	tor.acme.com

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search Users failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Unauthorized.

Error Sample Data

Search Users failed.

Status Code: 401.

Message: Unauthorized.

Set Investigation Status

Sets the status of investigations. If the investigations already have the specified status, then no changes will be made and the investigations will be returned.

READER NOTE

Investigation IDs or RRNs is a required parameter to run this command.

Run the List Investigations command to obtain the Investigation IDs or RRNs. Investigation IDs or RRNs can be found in the raw data at the path $.data[*].id for Investigation IDs or $.data[*].rrn for Investigation RRNs.

Input

Input Parameter

Required/Optional

Description

Example

Investigation IDs or RRNs

Required

The investigation IDs or RRNs used to change the investigation status.

For API v1, use either Investigation IDs or RRNs.
For API v2, use RRNs only.

Investigation IDs or RRNs can be obtained using the List Investigations command.

JSON

[
  "rrn:*****T2A4"
]

Status

Required

The new status for the investigation. Available options are:

Open
Closed
Investigating

Open

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Set Investigation Status failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The provided API Key is not authorized to perform the requested operation. Please check the permissions associated with the key. If the problem persists, contact Rapid7 support with the correlation Id from the response.

Error Sample Data

Set Investigation Status failed.

Status Code: 403.

Message: The provided API Key is not authorized to perform the requested operation. Please check the permissions associated with the key. If the problem persists, contact Rapid7 support with the correlation Id from the response.

Update Alerts

Updates information for the specified alerts.

READER NOTE

Alert RRNs is a required parameter to run this command.

Run the Search Alerts or the Fetch Event command with Event Type set to Investigation to obtain the Alert RRNs. Alert RRNs can be found in the raw data at the paths:
- $.alerts[*].rrn or $.rrns for Search Alerts
- $.data[*].rrn for Fetch Event

Assignee ID and Investigation RRN are optional parameters to run this command.

Run the Get Alert Available Assignees command to obtain the Assignee ID. Assignee IDs can be found in the raw data at the path $.users[*].id.
Run the List Investigations command to obtain the Investigation RRN. Investigation RRNs can be found in the raw data at the path $.data[*].rrn.

Input

Input Parameter	Required/Optional	Description	Example
Alert RRNs	Required	The RRNs of the alerts to update. Alert RRNs can be obtained using the Search Alerts or Fetch Event command, with Event Type set to Investigation.	JSON `[ "rrn:alerts:ca:***:alert:1:***" ]`
Status	Optional	The updated status. Available options are: Unmapped Open Investigating Waiting Closed	Investigating
Disposition	Optional	The updated disposition. Available options are: Unmapped Undecided Malicious Benign Unknown Not Applicable	Undecided
Priority	Optional	The updated priority. Available options are: Unmapped Info Low Medium High Critical	High
Assignee ID	Optional	The ID of the updated assignee. Assignee ID can be obtained using the Get Alert Available Assignees command.	*****
Investigation RRN	Optional	The RRN of the investigation to which the alerts belong. Investigation RRNs can be obtained using the List Investigations command.	rrn:investigation:ca:***:investigation:***
Tag Action	Optional	The action to apply to the tag. Available options are: Add Remove By default, the value is set to Add.	Add
Tags	Optional	The tags to be added to or removed from the alerts.	JSON `[ "Tag1" ]`
Comment	Optional	The comment to add to the alerts.	This is a test comment.

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Alerts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Forbidden.

Error Sample Data

Update Alerts failed.

Status Code: 403.

Message: Forbidden.

Update Investigations

Updates fields for the specified investigations. The investigations will be returned with the updated fields.

READER NOTE

Investigation IDs or RRNs is a required parameter to run this command.

Run the List Investigations command to obtain the Investigation IDs or RRNs. Investigation IDs or RRNs can be found in the raw data at the paths:
- $.data[*].id for Investigation IDs
- $.data[*].rrn for Investigation RRNs

Input

Input Parameter	Required/Optional	Description	Example
Multi-Customer	Optional	The option to indicate that the requester has multi-customer access when set to True. When set to True, use Investigation RRNs. By default, the value is set to False.	True
Investigation IDs or RRNs	Required	The investigation IDs or RRNs used to update the investigations. The updated fields apply to all investigations. For API v1, use either Investigation IDs or RRNs. For API v2, use RRNs only. Investigation IDs or RRNs can be obtained using the List Investigations command.	JSON `[ "rrn:investigation:ca:f424***cc7b:investigation:52YX***V22A" ]`
Title	Optional	The new name for the investigations. The title will remain unchanged when omitted.	New Name of Investigation 1031a
Status	Optional	The new status for the investigations. Available options are: Open Closed Investigating The status will remain unchanged when omitted.	OPEN
Priority	Optional	The new priority for the investigations. Available options are: Critical High Medium Low Unspecified The priority will remain unchanged when omitted.	HIGH
Disposition	Optional	The new disposition for the investigations. Available options are: Benign Malicious Not Applicable The disposition will remain unchanged when omitted.	BENIGN
User Email Address	Optional	The email address of the user to assign to the investigations. This is the email address associated with the assigned user’s Insight Platform account.	user@example.com
Threat Command Close Reason	Optional	The Threat Command reason for closing the investigations. This parameter applies only if the investigations have an associated alert in Threat Command. Available options are: Problem Solved Informational Only Problem We Are Already Aware Of Not Related To My Company False Positive Legitimate Application/Profile Company Owned Domain Other The Close Reason description depends on the Threat Command alert type.	False Positive
Threat Command Free Text	Optional	Additional information to provide when closing a Threat Command alert.	False positive alert

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data displays Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Update Investigations failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR V2 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Incorrect region in RRN: rrn:investigation:ca:f42415c3-3964-44c9-be64-592bf9bdcc7b:investigation:52YX8CP7V22A. Expected 'us2' but was 'ca'.

Error Sample Data

Update Investigations failed.

Status Code: 400.

Message: Incorrect region in RRN: rrn:investigation:ca:f42415c3-3964-44c9-be64-592bf9bdcc7b:investigation:52YX8CP7V22A. Expected 'us2' but was 'ca'.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Output Type

Description

Return Data Type

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

More details about an error can be viewed in the Error tab.

String

Error Handling

If the Return Data displays Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Rapid7 InsightIDR portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The provided API Key is not authorized to perform the requested operation. Please check the permissions associated with the key. If the problem persists, contact Rapid7 support with the correlation Id from the response.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: The provided API Key is not authorized to perform the requested operation. Please check the permissions associated with the key. If the problem persists, contact Rapid7 support with the correlation Id from the response.