---
title: "ListNotifications"
method: POST
path: "/gitpod.v1.NotificationService/ListNotifications"
tags: ["gitpod.v1.NotificationService"]
---

# ListNotifications

`POST /gitpod.v1.NotificationService/ListNotifications`

Lists notifications for the authenticated user.
 Response includes unread_count and total_count for the inbox badge.

 ### Examples

 - List all notifications:

   ```yaml
   pagination:
     pageSize: 20
   ```

 - List unread notifications:

   ```yaml
   pagination:
     pageSize: 20
   read: false
   ```

## Query parameters

- `pageSize` integer
- `token` string

## Request body

- GitpodV1ListNotificationsRequest
  - `pagination` GitpodV1PaginationRequest
    - `pageSize` integer — Page size is the maximum number of results to retrieve per page. Defaults to 25. Maximum 100.
    - `token` string — Token for the next set of results that was returned as next_token of a PaginationResponse
  - `read` boolean, nullable — Filter by read status. If not set, returns all notifications.
  - `types` GitpodV1NotificationType[] — Filter by notification types. If empty, returns all types.

## Response `200`

Success

- GitpodV1ListNotificationsResponse
  - `notifications` GitpodV1Notification[] — unresolved $ref
  - `pagination` GitpodV1PaginationResponse
    - `nextToken` string — Token passed for retrieving the next set of results. Empty if there are no more results
  - `totalCount` integer
  - `unreadCount` integer — Counts for the inbox badge. Always returned regardless of filters.

## Other responses

- `default` — Error

## Changes

- **2026-07-30** `44d50c2ac284` — 3 breaking, 8 warning, 15 info
  - removed the enum value `NOTIFICATION_TYPE_GROUP_ADDED` of the request property `types/items/`
  - removed the enum value `NOTIFICATION_TYPE_GROUP_REMOVED` of the request property `types/items/`
  - added `subschema #1, subschema #2, subschema #3, subschema #4, subschema #5, subschema #6` to the `notifications/items/context` response property `oneOf` list for the response status `200`
  - added the new `NOTIFICATION_TYPE_DYNAMIC_LLM_REQUEST_HEADER_FAILED` enum value to the `notifications/items/type` response property for the response status `200`
  - …22 more
- **2026-04-02** `dabc0ff98cd7` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/gitpod-io/apis/gitpod-v1/changes/gitpod.v1.NotificationService/ListNotifications/post.md)

---

[API](https://skmtc.dev/gitpod-io/apis/gitpod-v1.md) · [All operations](https://skmtc.dev/gitpod-io/apis/gitpod-v1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gitpod-io/gitpod-v1/revisions/44d50c2ac284/schema)