This page documents experimental API endpoints and is kept for historical purposes only. See the [finalized version]({{< relref "methods/grouped_notifications" >}}) if you want to implement the grouped notifications feature in a client.
This page is about grouped notifications, which we implemented server-side so that:
- grouping is consistent across clients
- clients do not run into the issue of going through entire pages that do not contribute to any new group; instead, notifications are already deduplicated server-side
The API shape is a bit different from the non-grouped notifications, because large notification groups usually tend to involve the same accounts, and moving accounts to a root key can avoid a lot of duplication, resulting in less server-side work and smaller network payloads.
## Get all grouped notifications {#get-grouped}
```http
GET /api/v2_alpha/notifications HTTP/1.1
```
Return grouped notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and `id` values.
Notifications of type `favourite` or `reblog` with the same type and the same target made in a similar timeframe are given a same `group_key` by the server, and querying this endpoint will return aggregated notifications, with only one object per `group_key`. Other notification types (such as `follow`) may be grouped in the future.
Types to filter include:
-`mention` = Someone mentioned you in their status
-`status` = Someone you enabled notifications for has posted a status
-`reblog` = Someone boosted one of your statuses
-`follow` = Someone followed you
-`follow_request` = Someone requested to follow you
-`favourite` = Someone favourited one of your statuses
-`poll` = A poll you have voted in or created has ended
-`update` = A status you boosted with has been edited
-`admin.sign_up` = Someone signed up (optionally sent to admins)
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
##### Query parameters
max_id
: String. All results returned will be about notifications strictly older than this notification ID. In effect, sets an upper bound on results.
since_id
: String. All results returned will be about notifications strictly newer than this notification ID. In effect, sets a lower bound on results.
min_id
: String. Returns results about notifications immediately newer than this notification ID. In effect, sets a cursor at this ID and paginates forward.
limit
: Integer. Maximum number of results to return. Defaults to 40 notifications. Max 80 notification groups.
types[]
: Array of String. Types to include in the result.
exclude_types[]
: Array of String. Types to exclude from the results.
account_id
: String. Return only notifications received from the specified account.
expand_accounts
: String. One of `full` (default) or `partial_avatars`. When set to `partial_avatars`, some accounts will not be rendered in full in the returned `accounts` list but will be instead returned in stripped-down form in the `partial_accounts` list. The most recent account in a notification group is always rendered in full in the `accounts` attribute.
: Array of String. Restrict which notification types can be grouped. Use this if there are notification types for which your client does not support grouping. If omitted, the server will group notifications of all types it supports (currently, `favourite` and `reblog`). If you do not want any notification grouping, use [GET `/api/v1/notifications`]({{< relref "methods/notifications#get" >}}) instead.
: {{<required>}} String. The group key of the notifications to discard.
##### Headers
Authorization
: {{<required>}} Provide this header with `Bearer <user token>` to gain authorized access to this API method.
#### Response
##### 200: OK
Upon a successful request, notifications with the given group key are successfully dismissed.
```json
{}
```
##### 401: Unauthorized
Invalid or missing Authorization header.
```json
{
"error": "The access token is invalid"
}
```
---
## Get the number of unread notifications {#unread-group-count}
```http
GET /api/v2_alpha/notifications/unread_count HTTP/1.1
```
Get the (capped) number of unread notification groups for the current user.
A notification is considered unread if it is more recent than the [notifications read marker]({{< relref "methods/markers" >}}).
Because the count is dependant on the parameters, it is computed every time and is thus a relatively slow operation (although faster than getting the full corresponding notifications), therefore the number of returned notifications is capped.
: Array of String. Restrict which notification types can be grouped. Use this if there are notification types for which your client does not support grouping. If omitted, the server will group notifications of all types it supports (currently, `favourite` and `reblog`). If you do not want any notification grouping, use [GET `/api/v1/notifications/unread_count`]({{< relref "methods/notifications#unread-count" >}}) instead.
**Description:** Partial accounts referenced by grouped notifications. Those are only returned when requesting grouped notifications with `expand_accounts=partial_avatars`.
**Type:** Array of [PartialAccountWithAvatar](#PartialAccountWithAvatar)\
These are stripped-down versions of [Account]({{< relref "entities/Account" >}}) that only contain what is necessary to display a list of avatars, as well as a few other useful properties. The aim is to cut back on expensive server-side serialization and reduce the network payload size of notification groups.
**Description:** ID of the oldest notification from this group represented within the current page. This is only returned when paginating through notification groups. Useful when polling new notifications.\
**Description:** ID of the newest notification from this group represented within the current page. This is only returned when paginating through notification groups. Useful when polling new notifications.\
**Description:** Date at which the most recent notification from this group within the current page has been created. This is only returned when paginating through notification groups.\
**Description:** ID of the [Status]({{< relref "entities/Status" >}}) that was the object of the notification. Attached when `type` of the notification is `favourite`, `reblog`, `status`, `mention`, `poll`, or `update`.\
**Description:** Summary of the event that caused follow relationships to be severed. Attached when `type` of the notification is `severed_relationships`.\
