investigations

Creates, updates, deletes, gets or lists an investigations resource.

Overview

Name	investigations
Type	Resource
Id	aws.guardduty.investigations

Fields

The following fields are returned by SELECT queries:

get_investigation

Name	Datatype	Description
cloud	object	Details about the cloud environment in which the investigation was performed, including the provider, region, and account.
confidence	string	The confidence level of the investigation's assessment. Possible values are Unknown, Low, Medium, and High. (Unknown, Low, Medium, High)
end_time	string (date-time)	The timestamp at which the investigation completed.
error	string	Details about the error if the investigation status is FAILED.
investigation_id	string	The unique identifier of the investigation. (pattern: <code>[a-fA-F0-9-]+</code>)
metadata	object	Metadata about the product and version that produced the investigation.
risk	string	A human-readable description of the assessed risk.
risk_level	string	The assessed risk level of the investigated threat. Possible values are Info, Low, Medium, High, and Critical. (Info, Low, Medium, High, Critical)
start_time	string (date-time)	The timestamp at which the investigation started.
status	string	The current status of the investigation. Possible values are RUNNING, COMPLETED, and FAILED. (RUNNING, COMPLETED, FAILED)
summary	string	A structured summary of the investigation findings, including affected resources, threat assessment, and recommended remediation steps.
trigger_prompt	string	The natural-language prompt that initiated this investigation.
triggered_by	string	The account that initiated the investigation.

list_investigations

Name	Datatype	Description
account_id	string	The Amazon Web Services account ID associated with the investigation.
confidence	string	The confidence level of the investigation's assessment. (Unknown, Low, Medium, High)
end_time	string (date-time)	The timestamp at which the investigation completed.
investigation_id	string	The unique identifier of the investigation. (pattern: <code>[a-fA-F0-9-]+</code>)
risk_level	string	The assessed risk level of the investigated threat. (Info, Low, Medium, High, Critical)
start_time	string (date-time)	The timestamp at which the investigation started.
status	string	The current status of the investigation. (RUNNING, COMPLETED, FAILED)
title	string	A short title summarizing the investigation.
trigger_prompt	string	The natural-language prompt that initiated this investigation.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_investigation	select	detector_id, investigation_id, region		This API is currently available as a preview. This feature is available in the following Amazon Web Services Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Canada (Central), Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris), Europe (Stockholm), and Asia Pacific (Tokyo). Retrieves the results and status of a specific GuardDuty investigation. An administrator account can retrieve any investigation within the organization. Member accounts can only retrieve investigations that belong to them.
list_investigations	select	detector_id, region		This API is currently available as a preview. This feature is available in the following Amazon Web Services Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Canada (Central), Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris), Europe (Stockholm), and Asia Pacific (Tokyo). Returns a list of investigations associated with the specified GuardDuty detector. An administrator account sees all investigations across the organization. Member accounts see only the investigations that belong to them.
create_investigation	insert	detector_id, region, TriggerPrompt		This API is currently available as a preview. During the preview, you can initiate up to 10 investigations per account per day, with a total limit of 100 investigations per account. This feature is available in the following Amazon Web Services Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Canada (Central), Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris), Europe (Stockholm), and Asia Pacific (Tokyo). Initiates a GuardDuty investigation that automatically analyzes security findings, correlates related activity, performs account-level analysis, and produces a structured investigation summary with recommended next steps. Only the administrator account can create an investigation. Member accounts don't have permission to create investigations from their accounts. To use this operation, the AI_ANALYST feature must be enabled on your detector. This feature uses Amazon Bedrock models that leverage Cross-Region Inference (CRIS), which automatically selects the optimal Amazon Web Services Region within your geography to process the investigation analysis and generate the investigation report. This maximizes available compute resources, model availability, and delivers the best customer experience. Your data remains stored only in the Region where the investigation request originates, however, investigation data and summary results may be processed outside that Region. All data is transmitted encrypted across Amazon's secure network. For more information, see GuardDuty Investigation.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
detector_id	string	The unique ID of the GuardDuty detector for the account in which the investigation is created. To find the detectorId in the current Region, see the Settings page in the GuardDuty console, or run the ListDetectors API.
investigation_id	string	The unique identifier of the investigation to retrieve.
region	string	AWS region (default: us-east-1)

SELECT examples

get_investigation

This API is currently available as a preview. This feature is available in the following Amazon Web Services Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Canada (Central), Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris), Europe (Stockholm), and Asia Pacific (Tokyo). Retrieves the results and status of a specific GuardDuty investigation. An administrator account can retrieve any investigation within the organization. Member accounts can only retrieve investigations that belong to them.

SELECT
cloud,
confidence,
end_time,
error,
investigation_id,
metadata,
risk,
risk_level,
start_time,
status,
summary,
trigger_prompt,
triggered_by
FROM aws.guardduty.investigations
WHERE detector_id = '{{ detector_id }}' -- required
AND investigation_id = '{{ investigation_id }}' -- required
AND region = '{{ region }}' -- required
;

list_investigations

This API is currently available as a preview. This feature is available in the following Amazon Web Services Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Canada (Central), Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris), Europe (Stockholm), and Asia Pacific (Tokyo). Returns a list of investigations associated with the specified GuardDuty detector. An administrator account sees all investigations across the organization. Member accounts see only the investigations that belong to them.

SELECT
account_id,
confidence,
end_time,
investigation_id,
risk_level,
start_time,
status,
title,
trigger_prompt
FROM aws.guardduty.investigations
WHERE detector_id = '{{ detector_id }}' -- required
AND region = '{{ region }}' -- required
;

INSERT examples

create_investigation

This API is currently available as a preview. During the preview, you can initiate up to 10 investigations per account per day, with a total limit of 100 investigations per account. This feature is available in the following Amazon Web Services Regions: US East (N. Virginia), US East (Ohio), US West (Oregon), Canada (Central), Europe (Frankfurt), Europe (Ireland), Europe (London), Europe (Paris), Europe (Stockholm), and Asia Pacific (Tokyo). Initiates a GuardDuty investigation that automatically analyzes security findings, correlates related activity, performs account-level analysis, and produces a structured investigation summary with recommended next steps. Only the administrator account can create an investigation. Member accounts don't have permission to create investigations from their accounts. To use this operation, the AI_ANALYST feature must be enabled on your detector. This feature uses Amazon Bedrock models that leverage Cross-Region Inference (CRIS), which automatically selects the optimal Amazon Web Services Region within your geography to process the investigation analysis and generate the investigation report. This maximizes available compute resources, model availability, and delivers the best customer experience. Your data remains stored only in the Region where the investigation request originates, however, investigation data and summary results may be processed outside that Region. All data is transmitted encrypted across Amazon's secure network. For more information, see GuardDuty Investigation.

INSERT INTO aws.guardduty.investigations (
TriggerPrompt,
ClientToken,
detector_id,
region
)
SELECT 
'{{ TriggerPrompt }}' /* required */,
'{{ ClientToken }}',
'{{ detector_id }}',
'{{ region }}'
RETURNING
investigation_id
;

Manifest

# Description fields are for documentation purposes
- name: investigations
props:
  - name: detector_id
    value: "{{ detector_id }}"
    description: Required parameter for the investigations resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the investigations resource.
  - name: TriggerPrompt
    value: "{{ TriggerPrompt }}"
  - name: ClientToken
    value: "{{ ClientToken }}"