This document explains how-tos for using the Service Health API to manage
events affecting a single project.

## Before you begin


[Verify that billing is enabled for your Google Cloud project](https://docs.cloud.google.com/billing/docs/how-to/verify-billing-enabled.md.txt#confirm_billing_is_enabled_on_a_project).

1. [Enable the Service Health API](https://docs.cloud.google.com/service-health/docs/manage-access.md.txt#enable-service-health-api-single-project) for the project you want to manage events for.
2. Set [permissions to access the Service Health API](https://docs.cloud.google.com/service-health/docs/manage-access.md.txt#access-service-health-api-dashboard).

## References

See the Events API reference ([v1](https://docs.cloud.google.com/service-health/docs/reference/rest/v1/projects.locations.events.md.txt), [v1beta](https://docs.cloud.google.com/service-health/docs/reference/rest/v1beta/projects.locations.events.md.txt))
for the methods you can use and the meaning of the fields in the responses.
In the API response, each entry in the `impact` list includes the granular
disruption `state` (`AFFECTED` or `RESOLVED`), `startTime`, and `endTime` (when
resolved) for each impacted product and location.

When setting the product or location, use the values found at
[Google Cloud products](https://docs.cloud.google.com/service-health/docs/supported-products-locations.md.txt) and
[locations](https://docs.cloud.google.com/service-health/docs/supported-products-locations.md.txt#locations).

## List all active incidents for a project

See the [quickstart](https://docs.cloud.google.com/service-health/docs/list-events.md.txt#list_all_active_incidents_for_a_project).

## Get incident details

You can use the Get API to view detailed information about an event.


Before using any of the request data,
make the following replacements:

- <var class="edit" scope="API_VERSION" translate="no">API_VERSION</var>: The API version to use. Use `v1` or `v1beta`.
- <var class="edit" scope="PROJECT_ID" translate="no">PROJECT_ID</var>: your Google Cloud project ID.
- <var class="edit" scope="EVENT_ID" translate="no">EVENT_ID</var>: the ID of the event.


HTTP method and URL:

```
GET https://servicehealth.googleapis.com/API VERSION/projects/PROJECT_ID/locations/global/events/EVENT_ID
```

To send your request, expand one of these options:

#### curl (Linux, macOS, or Cloud Shell)

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) , or by using [Cloud Shell](https://docs.cloud.google.com/shell/docs.md.txt), which automatically logs you into the `gcloud` CLI . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Execute the following command:

```
curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://servicehealth.googleapis.com/API VERSION/projects/PROJECT_ID/locations/global/events/EVENT_ID"
```

#### PowerShell (Windows)

> [!NOTE]
> **Note:** The following command assumes that you have logged in to the `gcloud` CLI with your user account by running [`gcloud init`](https://docs.cloud.google.com/sdk/gcloud/reference/init) or [`gcloud auth login`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/login.md.txt) . You can check the currently active account by running [`gcloud auth list`](https://docs.cloud.google.com/sdk/gcloud/reference/auth/list.md.txt).


Execute the following command:

```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://servicehealth.googleapis.com/API VERSION/projects/PROJECT_ID/locations/global/events/EVENT_ID" | Select-Object -Expand Content
```

You should receive a JSON response similar to the following:

```
{
  "name": "projects/PROJECT_ID/locations/global/events/EVENT_ID",
      "title": "We are experiencing a connectivity issue affecting Google Cloud SQL in us-east1, australia-southeast2.",
      "description": "The issue with Google Cloud SQL has been resolved for all affected projects as of Tuesday, 2022-10-18 11:00 US/Pacific. We thank you for your patience while we worked on resolving the issue.",
      "category": "INCIDENT",
      "detailedCategory": "CONFIRMED_INCIDENT",
      "state": "CLOSED",
      "detailedState": "RESOLVED",
      "artifacts": [
        {
          "artifact": "projects/PROJECT_ID/locations/global/artifacts/artifact_id",
          "artifactCategory": "ARTIFACT_CATEGORY_INCIDENT_REPORT",
        }
      ],
      "eventImpacts": [
        {
          "product": {
            "productName": "Google Cloud SQL",
            "id": "hV87iK5DcEXKgWU2kDri",
          },
          "location": {
            "locationName": "us-central1",
          }
        }
      ],
      "relevance": "RELATED",
   "updates": [
    {
      "updateTime": "2022-10-18T17:41:20.112287Z",
              "title": "We are experiencing a connectivity issue affecting Google Cloud SQL in us-east1, australia-southeast2.",
      "description": "We are experiencing an intermittent issue with Google Cloud SQL. Our engineering team continues to investigate the issue.",
      "symptom": "None at this time.",
      "workaround": "None at this time."
    },
    {
      "updateTime": "2022-10-18T18:00:05.690761Z",
      "title": "We are experiencing a connectivity issue affecting Google Cloud SQL in us-east1, australia-southeast2.",
      "description": "The issue with Google Cloud SQL has been resolved for all affected projects as of Tuesday, 2022-10-18 11:00 US/Pacific.\n\nWe thank you for your patience while we worked on resolving the issue.",
      "symptom": "None at this time.",
      "workaround": "None at this time."
    }
  ],
  "updateTime": "2022-10-18T18:00:05.690761Z",
  "startTime": "2022-10-18T17:41:20.112287Z",
  "endTime":  "2022-10-18T18:00:05.690761Z",
}
```

If you don't have the
permissions to get events,
you will get the following `PERMISSION_DENIED` error.

    {
      "error": {
        "code": 403,
        "message": "Permission 'servicehealth.events.get' denied on resource '//servicehealth.googleapis.com/projects/PROJECT_ID/locations/global/events/EVENT_ID' (or it may not exist).",
        "status": "PERMISSION_DENIED",
        "details": [
          {
            "@type": "type.googleapis.com/google.rpc.ErrorInfo",
            "reason": "IAM_PERMISSION_DENIED",
            "domain": "servicehealth.googleapis.com",
            "metadata": {
              "resource": "projects/PROJECT_ID/locations/global/events/EVENT_ID",
              "permission": "servicehealth.events.get"
            }
          }
        ]
      }
    }

To fix the error, set the [required permissions](https://docs.cloud.google.com/service-health/docs/manage-access.md.txt#access-service-health-api-dashboard).

## List impacted resources in a project

> [!WARNING]
>
> **Preview**
>
>
> This product or feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section
> of the [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA products and features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

For
[supported Google Cloud products](https://docs.cloud.google.com/service-health/docs/supported-products-locations.md.txt#resource-level-impact),
you can list the specific Google Cloud resources in your project that are
impacted by a Personalized Service Health event.

To list impacted resources, the Service Health API
(`servicehealth.googleapis.com`) must be enabled on the project at least 24
hours before the event starts, and your principal must have the
`servicehealth.impacts.list` permission (included in
`roles/servicehealth.viewer`).

#### REST API (v1beta)

To list impacted resources in a project, send a request to the Service Health API with the following parameters:

| Parameter | Value | Description |
|---|---|---|
| `parent` | `projects/PROJECT_ID/locations/global` | Required. Project ID or project number where you want to list impacted resources. |
| `pageSize` | 1 to 100 | Optional. Maximum number of impacts to return per page. When unspecified, defaults to 10. |
| `pageToken` | string | Optional. Token from a previous `ListImpactsResponse` to retrieve the next page of results. |
| `filter` | string | Optional. Filter expression to scope the returned impacts. For example, to list resources impacted by a specific event, set `filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID`. |

Before using any of the request data, make the following replacements:

- `PROJECT_ID`: your Google Cloud project ID or project number.

HTTP method and URL:

```
GET https://servicehealth.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/impacts
```

To use curl, call the GET endpoint directly:

```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://servicehealth.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/impacts"
```

#### gcloud

Run the following command to list impacted resources in a project:

```
gcloud beta service-health impacts list \
    --project=PROJECT_ID \
    --location=global
```

To list only the resources impacted by a specific event, pass the `--filter` flag:

```
gcloud beta service-health impacts list \
    --project=PROJECT_ID \
    --location=global \
    --filter="events:projects/PROJECT_ID/locations/global/events/EVENT_ID"
```

If the request is successful, the response body contains a list of [`Impact`](https://docs.cloud.google.com/service-health/docs/reference/rest/v1beta/projects.locations.impacts.md.txt#Impact) objects similar to the following:

```
{
  "impacts": [
    {
      "name": "projects/my-project/locations/global/impacts/f9a8b7c6-d5e4-4f3a-9b2c-1d0e9f8a7b6c",
      "events": [
        "projects/my-project/locations/global/events/1234567890abcdef"
      ],
      "asset": {
        "assetName": "//cloudsql.googleapis.com/projects/9876543210/instances/prod-orders-db",
        "assetType": "sqladmin.googleapis.com/Instance"
      },
      "description": "Instance experienced elevated connection errors during regional network disruption.",
      "createTime": "2026-10-08T14:12:05.120450Z",
      "updateTime": "2026-10-08T14:12:05.120450Z"
    }
  ]
}
```

### Common filter examples for impacted resources

You can pass a `filter` query parameter (or `--filter` in the Google Cloud CLI) to
narrow the returned `Impact` records:

- **List impacted resources for a specific event** : `filter=events:projects/PROJECT_ID/locations/global/events/EVENT_ID`
- **List impacted resources of a specific resource type** (for example, Cloud SQL instances): `filter=asset.assetType="sqladmin.googleapis.com/Instance"`
- **List impacted resources updated after a specific timestamp** : `filter=updateTime>"2026-10-08T00:00:00Z"`

## Get details about an impacted resource

> [!WARNING]
>
> **Preview**
>
>
> This product or feature is
>
> subject to the "Pre-GA Offerings Terms" in the General Service Terms section
> of the [Service Specific
> Terms](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA products and features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

You can retrieve a specific `Impact` record using its `IMPACT_ID`.

#### REST API (v1beta)

To get details about a specific impacted resource record, send a request with the following parameter:

| Parameter | Value | Description |
|---|---|---|
| `name` | `projects/PROJECT_ID/locations/global/impacts/IMPACT_ID` | Required. Full resource name of the `Impact` record to retrieve. |

HTTP method and URL:

```
GET https://servicehealth.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/impacts/IMPACT_ID
```

```
curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  "https://servicehealth.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/impacts/IMPACT_ID"
```

#### gcloud

Run the following command to get details about an impacted resource record:

```
gcloud beta service-health impacts describe IMPACT_ID \
    --project=PROJECT_ID \
    --location=global
```

If the request is successful, the response body contains an [`Impact`](https://docs.cloud.google.com/service-health/docs/reference/rest/v1beta/projects.locations.impacts.md.txt#Impact) object:

```
{
  "name": "projects/my-project/locations/global/impacts/f9a8b7c6-d5e4-4f3a-9b2c-1d0e9f8a7b6c",
  "events": [
    "projects/my-project/locations/global/events/1234567890abcdef"
  ],
  "asset": {
    "assetName": "//cloudsql.googleapis.com/projects/9876543210/instances/prod-orders-db",
    "assetType": "sqladmin.googleapis.com/Instance"
  },
  "description": "Instance experienced elevated connection errors during regional network disruption.",
  "createTime": "2026-10-08T14:12:05.120450Z",
  "updateTime": "2026-10-08T14:12:05.120450Z"
}
```