Create a Cloud Assist investigation

Important: As of April 10, 2026, creating, running, and editing investigations are only available to users that have a Premium Support contract or who have requested access through their account team. If you ran an investigation prior to April 10, 2026, the results of the investigation continue to be available to you in the Google Cloud console.

Use of this Preview offering of Gemini Cloud Assist is subject to the Google Cloud Agreement, including the Pre-GA Offering Terms of the Google Cloud Specific Service Terms, as supplemented by the terms for the Gemini for Google Cloud Trusted Tester Program.

This page shows you how to create and review Gemini Cloud Assist investigations.

Before you begin

1. Verify your project has the following APIs enabled:

   • cloudaicompanion.googleapis.com
   • cloudasset.googleapis.com
   • cloudresourcemanager.googleapis.com
   • geminicloudassist.googleapis.com
   • (Recommended) logging.googleapis.com
   • (Recommended) monitoring.googelapis.com

   See Enabling and disabling services for instructions on how to enable APIs.

2. In order to get the required permissions for creating an investigation, ask your administrator to grant you the Investigation Creator (roles/geminicloudassist.investigationCreator) IAM role on the project.

   This predefined role contains the permission required to create an investigation within your project. When you create an investigation, you're granted the Investigation Owner (roles/geminicloudassist.investigationOwner) IAM role on that investigation, which lets you review the results of the investigation.

3. Have access to the product being investigated.

   When you perform an investigation, Gemini Cloud Assist uses your credentials to access APIs and information. This means that the investigation's access is limited to the access that you have.

4. If you plan to perform an investigation on an application, the application must be contained within a folder configured for application management. Gemini Cloud Assist doesn't support applications created in a host project or a single-project boundary.

Create an investigation

Console

Important: The Investigations feature is integrated into multiple Google Cloud services and workflows. Your experience creating an investigation might have small differences from those outlined in this document. For example, some services can autofill information such as the Start time or the field for describing the issue.

1. To create a new investigation, click the Investigate button associated with your entry point. A typical entry point for creating an investigation is the Cloud Assist Investigations page.

   Go to Cloud Assist Investigations

2. Expand the Configure investigation drop-down.

3. (Optional) Enter an Investigation name for your investigation.

   The name you choose identifies this investigation in your investigation history. A name for the investigation is generated automatically if you skip this step.

4. Use the Select time range drop-down to select the span of time you want to investigate.

   An accurate start time enables time-based correlations to be made across seemingly unrelated events and adds more weight to events that occurred close to the start time. If you're unsure of the time range, you can run multiple investigations simultaneously with different time ranges.

5. Describe the issue that you're experiencing.

   You can copy and paste the exact error message you received, you can use natural language to explain the issue that you're experiencing, or you can include both.

6. If application investigations are supported by your entry point, then use the Application field to choose an application to investigate.

7. (Optional) Click + Add resource to select the resources that are affected by the issue you're experiencing.

   You can add resources either by using the resource picker or by inputting them manually. When inputting resources manually, you should consult the resource's reference documentation to ensure you use the correct format.

   You can't proceed with an investigation if you include any of the following:

   • Resources that are in a project or application that is outside the scope of the investigation.
   • Resources that are not supported.
   • Resources that are not recognized.

8. Click Create to begin the investigation.

The Details page for the investigation opens, and results appear in the page as they become available. It can take up to several minutes for the investigation to complete. If you leave the investigation's details page, you can check the status of the investigation by clicking the Notifications button ().

API

1. Create a JSON file that contains the following information:

   {
   "title": "INVESTIGATION_NAME",
   "observations": {
     "user.project": {
       "id": "user.project",
       "observationType": "OBSERVATION_TYPE_STRUCTURED_INPUT",
       "observerType": "OBSERVER_TYPE_USER",
       "text": "PROJECT_NAME"
     },
     "user.input.text": {
       "id": "user.input.text",
       "observationType": "OBSERVATION_TYPE_TEXT_DESCRIPTION",
       "observerType": "OBSERVER_TYPE_USER",
       "timeIntervals": [
         {
           "startTime": "ISSUE_START_TIME"
         }
       ],
       "text": "ISSUE_DESCRIPTION",
       "relevantResources": [
         "AFFECTED_RESOURCE"
       ],
     },
   }
   

   Replace the following:

   • INVESTIGATION_NAME: Enter a name for the investigation. For example Missing Cloud Storage bucket.

   • PROJECT_NAME: Enter the name of the project in which the investigation is being created. For example, my-project.

   • ISSUE_START_TIME: Enter the date and time when the issue that you're investigating began. For example, 2025-07-08T17:23:00Z.

   • ISSUE_DESCRIPTION: Enter a description of the issue you're experiencing. You can include the exact error message you received, you can use natural language to explain the issue that you're experiencing, or you can include both.

   • AFFECTED_RESOURCE: Enter the name of the resource involved in the issue you're experiencing. For example, //storage.googleapis.com/my-bucket. To ensure you use the correct format for a resource, you should consult the resource's reference documentation.

   For a full representation of an investigation resource, see the resource specification.

2. Obtain an access token:

   TOKEN=$(gcloud auth print-access-token)

3. Use the investigations.create method to create the investigation:

   curl -X POST --data-binary @JSON_FILE_NAME \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     "https://geminicloudassist.googleapis.com/v1alpha/projects/PROJECT_NAME/locations/global/investigations"
   

   Replace the following:

   • JSON_FILE_NAME: Enter the path to the JSON file you created earlier. For example, Desktop/my-investigation.json.

   • PROJECT_NAME: Enter the same project name that you included in the user.project observation.

4. In the response, copy the value in the revision parameter.

5. Use the investigations.revisions.run method to execute the investigation:

   curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     "https://geminicloudassist.googleapis.com/v1alpha/projects/REVISION_RESOURCE:run"
   

   Replace REVISION_RESOURCE with the value that you copied from the revision parameter.

It can take up to several minutes for the investigation to complete. You can check the status of the investigation by copying the value of the name parameter that was returned in the investigations.revisions.run response and using the value in the name parameter of an operations.get request.

Note: The user or service account that creates an investigation is granted the Investigation Owner (roles/geminicloudassist.investigationOwner) IAM role for that specific investigation as part of the creation process.

Review an Investigation

When working with investigations in the Google Cloud console, you can view the investigation details from the entry point where you initiated the investigation or from your project's investigation history.

An investigation contains the following sections:

1. The Investigation recap

   This section contains a high-level summary of the issue, the strategy Gemini took to investigate, and the key findings of the investigation.

2. The Hypotheses

   This section contains one or more hypothesis cards based on the data the investigation collected and the observations it made. You can find details for each hypothesis by click the View button in the relevant card.

   • The details for a hypothesis contain a What section describing what the issue could be and a Next steps section describing actions that either help you correct the issue or that provide you additional troubleshooting steps to confirm or refute the hypothesis.

     • If a remediation is supported for the issue that was identified in the hypothesis, a Generate plan button is included in the remediation steps. Clicking Generate Plan creates a step-by-step remediation plan, which includes concrete actions such as gcloud commands or Kubernetes manifests. After reviewing the plan, you can click Run to perform the actions described in the plan.

3. The Findings

   This section contains observations generated by the investigation and lists the Google Cloud resources involved in the investigation. Observations are based on reviews of procedural runbooks, logs, outage messages, and alerts.

   The findings section shows you what information Gemini used to generate the hypotheses and can be helpful for refining your investigation.

You can revise your investigation input using the Edit button, which lets you re-run the investigation with updated information. When an investigation has multiple runs associated with it, you can review the results of previous runs of the investigation using the Revision drop-down selector.

If you have a support package, you can click the Request support button found in the investigation's details page in order to file a support case. When you do, you can automatically populate the case details and share the investigation results with the support engineer.

What's next

• Learn more about investigations.
• View and manage existing investigations.