- [Resource: Investigation](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation)
  - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.SCHEMA_REPRESENTATION)
  - [AssociatedSubjects](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.AssociatedSubjects)
    - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.AssociatedSubjects.SCHEMA_REPRESENTATION)
  - [Verdict](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Verdict)
  - [InvestigationStatus](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationStatus)
  - [InvestigationNextStep](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationNextStep)
    - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationNextStep.SCHEMA_REPRESENTATION)
  - [Type](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Type)
  - [InvestigationTriggerType](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationTriggerType)
  - [Finding](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Finding)
    - [JSON representation](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Finding.SCHEMA_REPRESENTATION)
  - [Code](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Code)
- [Methods](https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#METHODS_SUMMARY)

## Resource: Investigation

An Investigation is a resource that captures analysis details of a particular threat or incident. It includes a final disposition (e.g., true positive, false positive), confidence score, recommended next steps, and a list of InvestigationStep items (timeline events). Investigation is optionally linked to an Alert via alerts.ids.

| JSON representation |
|---|
| ``` { "name": string, "displayName": string, "verdict": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Verdict`), "confidenceScore": number, "recommendedNextSteps": [ string ], "summary": string, "status": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationStatus`), "timeRange": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Interval`) }, "notebook": string, "severity": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/ProductSeverity`), "confidence": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/ProductConfidence`), "nextSteps": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationNextStep`) } ], "triggerType": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationTriggerType`), "experimental": boolean, "publishTime": string, "updateTime": string, "findings": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Finding`) } ], "associations": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Association`) } ], "investigationSteps": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations.investigationSteps#InvestigationStep`) } ], "entities": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.entities#Entity`) } ], "errorReason": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Code`), "filtered": boolean, "reviewed": boolean, "securityTokenCount": string, // The following is a list of mutually exclusive fields. At most one of the // fields will be set in a response: "alerts": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.AssociatedSubjects`) }, "cases": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.AssociatedSubjects`) } // End of mutually exclusive fields. } ``` |

| Fields ||
|---|---|
| `name` | `string` Output only. Identifier. The full resource name of the investigation. Format: projects/{project}/locations/{location}/instances/{instance}/investigations/{investigation} |
| `displayName` | `string` Required. The user-facing label for the investigation. |
| `verdict` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Verdict`)`` Optional. The final disposition of the investigation. |
| `confidenceScore` | `number` Optional. The confidence score of the investigation in the range \[1..100\]. |
| `recommendedNextSteps[] (deprecated)` | `string` > [!WARNING] > This item is deprecated! Optional. Recommended next steps, if any. This is a list of strings that can be displayed to the user. Use `nextSteps` instead. |
| `summary` | `string` Optional. A short summary or analysis result for this investigation. |
| `status` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationStatus`)`` Optional. The current status of the investigation. |
| `timeRange` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Interval`)`` Output only. The time range of the investigation. |
| `notebook` | `string` Output only. The resource name of notebook associated with the investigation. Format: projects/{project}/locations/{location}/instances/{instance}/notebooks/{notebook} |
| `severity` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/ProductSeverity`)`` The severity of the investigation. |
| `confidence` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/ProductConfidence`)`` The level of confidence in the investigation. |
| `nextSteps[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationNextStep`)`` Output only. Recommended next steps, if any. This is a list of strings that can be displayed to the user. |
| `triggerType` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.InvestigationTriggerType`)`` Output only. The trigger type of the investigation. Not required for manual investigations. |
| `experimental` | `boolean` Output only. Whether the investigation is experimental. |
| `publishTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Time when investigation was published. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `updateTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Output only. Time when investigation was last updated. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `findings[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Finding`)`` Output only. Detailed findings from the investigation. An investigation can have multiple findings. |
| `associations[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/Association`)`` Output only. Associations represents different metadata about malware and threat actors associated with an Investigation. |
| `investigationSteps[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations.investigationSteps#InvestigationStep`)`` Output only. Investigation steps taken by gemini during the investigation. |
| `entities[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.entities#Entity`)`` Output only. A list of network entities associated with the investigation. |
| `errorReason` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Code`)`` Optional. The error reason of the investigation, could be no error. |
| `filtered` | `boolean` Output only. Whether the investigation was filtered by the alert filter. |
| `reviewed` | `boolean` Output only. Indicates whether the investigation has been reviewed by the customer. This field is only relevant for MTD investigations. |
| `securityTokenCount` | `string (https://developers.google.com/discovery/v1/type-format format)` Output only. Total security tokens consumed by the investigation execution. |
| The subjects of the investigation, starting with alerts and cases. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response: ||
| `alerts` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.AssociatedSubjects`)`` The list of alerts associated with the investigation. |
| `cases` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.AssociatedSubjects`)`` The list of cases associated with the investigation. |
| End of mutually exclusive fields. ||

### AssociatedSubjects

AssociatedSubjects is a wrapper for a list of ids.

| JSON representation |
|---|
| ``` { "ids": [ string ] } ``` |

| Fields ||
|---|---|
| `ids[]` | `string` Output only. IDs of associated subjects. |

### Verdict

The final disposition assigned by the agent.

| Enums ||
|---|---|
| `VERDICT_UNSPECIFIED` | An unspecified verdict. |
| `TRUE_POSITIVE` | A categorization of the finding as a "true positive". |
| `FALSE_POSITIVE` | A categorization of the finding as a "false positive". |

### InvestigationStatus

| Enums ||
|---|---|
| `STATUS_UNSPECIFIED` | The status of the investigation is unspecified. |
| `STATUS_NOT_STARTED` | The investigation has not started. |
| `STATUS_IN_PROGRESS` | The investigation is in progress. |
| `STATUS_COMPLETED_SUCCESS` | The investigation has been completed successfully. |
| `STATUS_COMPLETED_ERROR` | The investigation has been completed with an error. |
| `STATUS_PENDING` | The investigation is in pending state. |

### InvestigationNextStep

InvestigationNextStep contains the recommended next steps for an investigation.

| JSON representation |
|---|
| ``` { "title": string, "type": enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Type`), "description": string } ``` |

| Fields ||
|---|---|
| `title` | `string` Output only. The recommended next steps for the investigation. |
| `type` | ``enum (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations#Investigation.Type`)`` Output only. The type of the recommended next steps. |
| `description` | `string` Output only. Remediation detail for the recommended next steps. |

### Type

The type of the recommended next steps.

| Enums ||
|---|---|
| `TYPE_UNSPECIFIED` | The next step type is unknown. |
| `SEARCHABLE` | The next step type is searchable. |
| `MANUAL` | The next step type is manual. |

### InvestigationTriggerType

The trigger type of the investigation.

| Enums ||
|---|---|
| `INVESTIGATION_TRIGGER_TYPE_UNSPECIFIED` | The trigger type is unknown. |
| `AGENT_MANUAL` | The trigger type is agent manual. |
| `AGENT_AUTO` | The trigger type is agent auto. |
| `MTD_ALERT` | The trigger type is MTD alert. |
| `MTD_HUNT` | The trigger type is MTD hunt. |
| `AGENT_AUTO_BY_MTD` | The trigger type is MTD auto. |

### Finding

Findings from the investigation.

| JSON representation |
|---|
| ``` { "narrative": string, "secopsQueryUri": string, "events": [ string ], "eventTime": string, "attackDetails": { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/SecurityResult#AttackDetails`) }, "sourceDataCitations": [ { object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/Citation`) } ] } ``` |

| Fields ||
|---|---|
| `narrative` | `string` Output only. A detailed analysis summary provided by the Mandiant Analyst. |
| `secopsQueryUri` | `string` Output only. The URI path to the SecOps search page for the events. For example: `/search?query=(metadata.id%20%3D%20b%22AAAAABZyPaaD2gq3NK6kPEZBWmEAAAAABgAAAAAAAAA%3D%22)` |
| `events[]` | `string` Output only. The UDM events associated with the findings. Example: events: \["projects/123/locations/us/instances/c17c06a4-7a45-4b1d-aaa9-d8bd5c6cb331/events/event1", "projects/123/locations/us/instances/c17c06a4-7a45-4b1d-aaa9-d8bd5c6cb331/events/event2"\] |
| `eventTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The timestamp of the first event found in the finding. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `attackDetails` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/Shared.Types/SecurityResult#AttackDetails`)`` Output only. The MITRE ATT\&CK details most closely represented by this finding. |
| `sourceDataCitations[]` | ``object (`https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/Citation`)`` Output only. The citations associated with the finding. Citations provide references to the source data that contributed to the finding. The maximum number of citations is 100. |

### Code

The canonical error codes for gRPC APIs.

Sometimes multiple error codes may apply. Services should return the most specific error code that applies. For example, prefer `OUT_OF_RANGE` over `FAILED_PRECONDITION` if both codes apply. Similarly prefer `NOT_FOUND` or `ALREADY_EXISTS` over `FAILED_PRECONDITION`.

| Enums ||
|---|---|
| `OK` | Not an error; returned on success. HTTP Mapping: 200 OK |
| `CANCELLED` | The operation was cancelled, typically by the caller. HTTP Mapping: 499 Client Closed Request |
| `UNKNOWN` | Unknown error. For example, this error may be returned when a `Status` value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error. HTTP Mapping: 500 Internal Server Error |
| `INVALID_ARGUMENT` | The client specified an invalid argument. Note that this differs from `FAILED_PRECONDITION`. `INVALID_ARGUMENT` indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name). HTTP Mapping: 400 Bad Request |
| `DEADLINE_EXCEEDED` | The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire. HTTP Mapping: 504 Gateway Timeout |
| `NOT_FOUND` | Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, `NOT_FOUND` may be used. If a request is denied for some users within a class of users, such as user-based access control, `PERMISSION_DENIED` must be used. HTTP Mapping: 404 Not Found |
| `ALREADY_EXISTS` | The entity that a client attempted to create (e.g., file or directory) already exists. HTTP Mapping: 409 Conflict |
| `PERMISSION_DENIED` | The caller does not have permission to execute the specified operation. `PERMISSION_DENIED` must not be used for rejections caused by exhausting some resource (use `RESOURCE_EXHAUSTED` instead for those errors). `PERMISSION_DENIED` must not be used if the caller can not be identified (use `UNAUTHENTICATED` instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions. HTTP Mapping: 403 Forbidden |
| `UNAUTHENTICATED` | The request does not have valid authentication credentials for the operation. HTTP Mapping: 401 Unauthorized |
| `RESOURCE_EXHAUSTED` | Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space. HTTP Mapping: 429 Too Many Requests |
| `FAILED_PRECONDITION` | The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`: (a) Use `UNAVAILABLE` if the client can retry just the failing call. (b) Use `ABORTED` if the client should retry at a higher level. For example, when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence. (c) Use `FAILED_PRECONDITION` if the client should not retry until the system state has been explicitly fixed. For example, if an "rmdir" fails because the directory is non-empty, `FAILED_PRECONDITION` should be returned since the client should not retry unless the files are deleted from the directory. HTTP Mapping: 400 Bad Request |
| `ABORTED` | The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`. HTTP Mapping: 409 Conflict |
| `OUT_OF_RANGE` | The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike `INVALID_ARGUMENT`, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate `INVALID_ARGUMENT` if asked to read at an offset that is not in the range \[0,2\^32-1\], but it will generate `OUT_OF_RANGE` if asked to read from an offset past the current file size. There is a fair bit of overlap between `FAILED_PRECONDITION` and `OUT_OF_RANGE`. We recommend using `OUT_OF_RANGE` (the more specific error) when it applies so that callers who are iterating through a space can easily look for an `OUT_OF_RANGE` error to detect when they are done. HTTP Mapping: 400 Bad Request |
| `UNIMPLEMENTED` | The operation is not implemented or is not supported/enabled in this service. HTTP Mapping: 501 Not Implemented |
| `INTERNAL` | Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors. HTTP Mapping: 500 Internal Server Error |
| `UNAVAILABLE` | The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations. See the guidelines above for deciding between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`. HTTP Mapping: 503 Service Unavailable |
| `DATA_LOSS` | Unrecoverable data loss or corruption. HTTP Mapping: 500 Internal Server Error |

| ## Methods ||
|---|---|
| ### `https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations/fetchAssociated` | FetchAssociatedInvestigations is used to fetch all the associated resources for each of the given alerts/cases. |
| ### `https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations/get` | GetInvestigation is used to retrieve an investigation. |
| ### `https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations/list` | ListInvestigations is used to retrieve existing investigations for a given instance. |
| ### `https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations/transitionReviewState` | TransitionInvestigationReviewState is used to update the review state of an investigation. |
| ### `https://docs.cloud.google.com/chronicle/docs/reference/rest/v1alpha/projects.locations.instances.investigations/trigger` | Custom method to manually trigger an investigation for a given alert. |