documentation/content/en/methods/notifications.md

title	description	menu	aliases
notifications API methods	Receive notifications for activity on your account or statuses.	docs weight name parent identifier 50 notifications methods methods-notifications	/methods/notifications /api/methods/notifications

Get all notifications

GET /api/v1/notifications HTTP/1.1

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.

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)
• admin.report = A new report has been filed

Returns: Array of [Notification]({{< relref "entities/Notification" >}})
OAuth: User token + read:notifications
Version history:
0.0.0 - added
2.6.0 - added min_id
2.9.0 - added account_id
3.1.0 - added follow_request type
3.3.0 - added status type; both min_id and max_id can be used at the same time now
3.5.0 - added types; add update and admin.sign_up types
4.0.0 - added admin.report type
4.1.0 - notification limit changed from 15 (max 30) to 40 (max 80)
4.3.0 - added include_filtered parameter

Request

Headers

Authorization

{{}} 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 lesser than this ID. In effect, sets an upper bound on results.

since_id

String. All results returned will be greater than this ID. In effect, sets a lower bound on results.

min_id

String. Returns results immediately newer than this 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 notifications.

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.

include_filtered

Boolean. Whether to include notifications filtered by the user's [NotificationPolicy]({{< relref "entities/NotificationPolicy" >}}). Defaults to false.

Response

Sample call with limit=2.

GET https://mastodon.social/api/v1/notifications?limit=2 HTTP/1.1
Authorization: Bearer <user_token>

200: OK

The response body contains one page of notifications. You can use the HTTP Link header for further pagination.

Link: <https://mastodon.example/api/v1/notifications?max_id=34975535>; rel="next", <https://mastodon.example/api/v1/notifications?min_id=34975861>;

[
  {
    "id": "34975861",
    "type": "mention",
    "created_at": "2019-11-23T07:49:02.064Z",
    "account": {
      "id": "971724",
      "username": "zsc",
      "acct": "zsc",
      // ...
    },
    "status": {
      "id": "103186126728896492",
      "created_at": "2019-11-23T07:49:01.940Z",
      "in_reply_to_id": "103186038209478945",
      "in_reply_to_account_id": "14715",
      // ...
      "content": "<p><span class=\"h-card\"><a href=\"https://mastodon.social/@trwnh\" class=\"u-url mention\">@<span>trwnh</span></a></span> sup!</p>",
      // ...
      "account": {
        "id": "971724",
        "username": "zsc",
        "acct": "zsc",
        // ...
      },
      // ...
      "mentions": [
        {
          "id": "14715",
          "username": "trwnh",
          "url": "https://mastodon.social/@trwnh",
          "acct": "trwnh"
        }
      ],
      // ...
    }
  },
  {
    "id": "34975535",
    "type": "favourite",
    "created_at": "2019-11-23T07:29:18.903Z",
    "account": {
      "id": "297420",
      "username": "haskal",
      "acct": "haskal@cybre.space",
      // ...
    },
    "status": {
      "id": "103186046267791694",
      "created_at": "2019-11-23T07:28:34.210Z",
      "in_reply_to_id": "103186044372624124",
      "in_reply_to_account_id": "297420",
      // ...
      "account": {
        "id": "14715",
        "username": "trwnh",
        "acct": "trwnh",
        // ...
      }
    }
  }
]

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Get a single notification

GET /api/v1/notifications/:id HTTP/1.1

View information about a notification with a given ID.

Returns: [Notification]({{< relref "entities/Notification" >}})
OAuth: User token + read:notifications
Version history:
0.0.0 - added

Request

Path parameters

:id

{{}} String. The ID of the Notification in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK

A single Notification

{
  "id": "34975861",
  "type": "mention",
  "created_at": "2019-11-23T07:49:02.064Z",
  "account": {
    "id": "971724",
    "username": "zsc",
    "acct": "zsc",
    // ...
  },
  "status": {
    "id": "103186126728896492",
    "created_at": "2019-11-23T07:49:01.940Z",
    "in_reply_to_id": "103186038209478945",
    "in_reply_to_account_id": "14715",
    // ...
    "content": "<p><span class=\"h-card\"><a href=\"https://mastodon.social/@trwnh\" class=\"u-url mention\">@<span>trwnh</span></a></span> sup!</p>",
    // ...
    "account": {
      "id": "971724",
      "username": "zsc",
      "acct": "zsc",
      // ...
    },
    // ...
    "mentions": [
      {
        "id": "14715",
        "username": "trwnh",
        "url": "https://mastodon.social/@trwnh",
        "acct": "trwnh"
      }
    ],
    // ...
  }
}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Dismiss all notifications

POST /api/v1/notifications/clear HTTP/1.1

Clear all notifications from the server.

Returns: Empty
OAuth: User token + write:notifications
Version history:
0.0.0 - added

Request

Headers

Authorization

{{}} Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK

Notifications successfully cleared.

{}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Dismiss a single notification

POST /api/v1/notifications/:id/dismiss HTTP/1.1

Dismiss a single notification from the server.

Returns: Empty
OAuth: User token + write:notifications
Version history:
1.3.0 - added

Request

Path parameters

:id

{{}} String. The ID of the Notification in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK

Notification with given ID successfully dismissed

{}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Dismiss a single notification {{%removed%}}

POST /api/v1/notifications/dismiss HTTP/1.1

Dismiss a single notification from the server.

Returns: Empty
OAuth: User token + write:notifications
Version history:
0.0.0 - available
1.3.0 - deprecated in favor of notifications/:id/dismiss 3.0.0 - removed

Request

Headers

Authorization

{{}} Provide this header with Bearer <user_token> to gain authorized access to this API method.

Form data parameters

id

{{}} String. The ID of the notification in the database.

Response

200: OK

Notification with given ID successfully dismissed

{}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Get the number of unread notifications

GET /api/v1/notifications/unread_count HTTP/1.1

Get the (capped) number of unread notifications 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.

Returns: Hash with a single key of count
OAuth: User token + read:notifications
Version history:
4.3.0 - added

Request

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Query parameters

limit

Integer. Maximum number of results to return. Defaults to 100 notifications. Max 1000 notifications.

types[]

Array of String. Types of notifications that should count towards unread notifications.

exclude_types[]

Array of String. Types of notifications that should not count towards unread notifications.

account_id

String. Only count unread notifications received from the specified account.

Response

200: OK

The response body contains the capped count of unread notifications.

{
  "count": 42,
}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Get the filtering policy for notifications

GET /api/v2/notifications/policy HTTP/1.1

Notifications filtering policy for the user.

Returns: [NotificationPolicy]({{< relref "entities/NotificationPolicy" >}})
OAuth: User token + read:notifications
Version history:
4.3.0 - added

Request

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

The response body contains the current notifications filtering policy for the user.

{
  "for_not_following": "accept",
  "for_not_followers": "accept",
  "for_new_accounts": "accept",
  "for_private_mentions": "drop",
  "for_limited_accounts": "filter",
  "summary": {
    "pending_requests_count": 0,
    "pending_notifications_count": 0
  }
}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Update the filtering policy for notifications

PATCH /api/v2/notifications/policy HTTP/1.1

Update the user's notifications filtering policy.

Returns: [NotificationPolicy]({{< relref "entities/NotificationPolicy" >}})
OAuth: User token + write:notifications
Version history:
4.3.0 - added

Request

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Form data parameters

for_not_following

String. Whether to accept, filter or drop notifications from accounts the user is not following. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing.

for_not_followers

String. Whether to accept, filter or drop notifications from accounts that are not following the user. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing.

for_new_accounts

String. Whether to accept, filter or drop notifications from accounts created in the past 30 days. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing.

for_private_mentions

String. Whether to accept, filter or drop notifications from private mentions. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing. Replies to private mentions initiated by the user, as well as accounts the user follows, are always allowed, regardless of this value.

for_limited_accounts

String. Whether to accept, filter or drop notifications from accounts that were limited by a moderator. drop will prevent creation of the notification object altogether (without preventing the underlying activity), filter will cause it to be marked as filtered, and accept will not affect its processing.

Response

200: OK

The response body contains the updated notifications filtering policy for the user.

{
  "filter_not_following": false,
  "filter_not_followers": false,
  "filter_new_accounts": false,
  "filter_private_mentions": true,
  "summary": {
    "pending_requests_count": 0,
    "pending_notifications_count": 0
  }
}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Get all notification requests

GET /api/v1/notifications/requests HTTP/1.1

Notification requests for notifications filtered by the user's policy. This API returns Link headers containing links to the next/previous page.

Returns: Array of [NotificationRequest]({{< relref "entities/NotificationRequest" >}})
OAuth: User token + read:notifications
Version history:
4.3.0 - added

Request

Headers

Authorization

{{}} 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 lesser than this ID. In effect, sets an upper bound on results.

since_id

String. All results returned will be greater than this ID. In effect, sets a lower bound on results.

min_id

String. Returns results immediately newer than this ID. In effect, sets a cursor at this ID and paginates forward.

limit

Integer. Maximum number of results to return. Defaults to 40 notification requests. Max 80 notification requests.

Response

200: OK

The response body contains one page of notification requests. You can use the HTTP Link header for further pagination.

Link: <https://mastodon.example/api/v1/notifications/requests?max_id=112456967201894256>; rel="next", <https://mastodon.example/api/v1/notifications/requests?min_id=112456967201894256>; rel="prev"

[
  {
    "id": "112456967201894256",
    "created_at": "2024-05-17T14:45:41.171Z",
    "updated_at": "2024-05-17T14:45:41.171Z",
    "notifications_count": "1",
    "account": {
      "id": "971724",
      "username": "zsc",
      "acct": "zsc",
      // ...
    },
    "last_status": {
      "id": "103186126728896492",
      "created_at": "2019-11-23T07:49:01.940Z",
      "in_reply_to_id": "103186038209478945",
      "in_reply_to_account_id": "14715",
      // ...
      "content": "<p><span class=\"h-card\"><a href=\"https://mastodon.social/@trwnh\" class=\"u-url mention\">@<span>trwnh</span></a></span> sup!</p>",
      // ...
      "account": {
        "id": "971724",
        "username": "zsc",
        "acct": "zsc",
        // ...
      },
      // ...
      "mentions": [
        {
          "id": "14715",
          "username": "trwnh",
          "url": "https://mastodon.social/@trwnh",
          "acct": "trwnh"
        }
      ],
      // ...
    }
  }
]

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Get a single notification request

GET /api/v1/notifications/requests/:id HTTP/1.1

View information about a notification request with a given ID.

Returns: [NotificationRequest]({{< relref "entities/NotificationRequest" >}})
OAuth: User token + read:notifications
Version history:
4.3.0 - added

Request

Path parameters

:id

{{}} String. The ID of the Notification in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

A single notification request.

  {
    "id": "112456967201894256",
    "created_at": "2024-05-17T14:45:41.171Z",
    "updated_at": "2024-05-17T14:45:41.171Z",
    "notifications_count": "1",
    "account": {
      "id": "971724",
      "username": "zsc",
      "acct": "zsc",
      // ...
    },
    "last_status": {
      "id": "103186126728896492",
      "created_at": "2019-11-23T07:49:01.940Z",
      "in_reply_to_id": "103186038209478945",
      "in_reply_to_account_id": "14715",
      // ...
      "content": "<p><span class=\"h-card\"><a href=\"https://mastodon.social/@trwnh\" class=\"u-url mention\">@<span>trwnh</span></a></span> sup!</p>",
      // ...
      "account": {
        "id": "971724",
        "username": "zsc",
        "acct": "zsc",
        // ...
      },
      // ...
      "mentions": [
        {
          "id": "14715",
          "username": "trwnh",
          "url": "https://mastodon.social/@trwnh",
          "acct": "trwnh"
        }
      ],
      // ...
    }
  }

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Accept a single notification request

POST /api/v1/notifications/requests/:id/accept HTTP/1.1

Accept a notification request, which merges the filtered notifications from that user back into the main notification and accepts any future notification from them.

Returns: Empty
OAuth: User token + write:notifications
Version history:
4.3.0 - added

Request

Path parameters

:id

{{}} String. The ID of the Notification in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

A successful call will return an empty object.

{}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Dismiss a single notification request

POST /api/v1/notifications/requests/:id/dismiss HTTP/1.1

Dismiss a notification request, which hides it and prevent it from contributing to the pending notification requests count.

Returns: Empty
OAuth: User token + write:notifications
Version history:
4.3.0 - added

Request

Path parameters

:id

{{}} String. The ID of the Notification in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

A successful call will return an empty object.

{}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Accept multiple notification requests

POST /api/v1/notifications/requests/accept HTTP/1.1

Accepts multiple notification requests, which merges the filtered notifications from those users back into the main notifications and accepts any future notification from them.

Returns: Empty
OAuth: User token + write:notifications
Version history:
4.3.0 - added

Request

Form data parameters

:id[]

{{}} Array of String. The IDs of the notification requests in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

A successful call will return an empty object.

{}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Dismiss multiple notification requests

POST /api/v1/notifications/requests/dismiss HTTP/1.1

Dismiss multiple notification requests, which hides them and prevent them from contributing to the pending notification requests count.

Returns: Empty
OAuth: User token + write:notifications
Version history:
4.3.0 - added

Request

Form data parameters

:id[]

{{}} Array of String. The IDs of the notification requests in the database.

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

A successful call will return an empty object.

{}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

Check if accepted notification requests have been merged

GET /api/v1/notifications/requests/merged

Check whether accepted notification requests have been merged. Accepting notification requests schedules a background job to merge the filtered notifications back into the normal notification list. When that process has finished, the client should refresh the notifications list at its earliest convenience. This is communicated by the notifications_merged streaming event but can also be polled using this endpoint.

*Returns: Hash with a single boolean attribute merged
OAuth: User token + read:notifications
Version history:
4.3.0 - added

Request

Headers

Authorization

{{}} Provide this header with Bearer <user token> to gain authorized access to this API method.

Response

200: OK

A successful call returns whether the notifications have been merged and are ready for being loaded.

{
  "merged": false
}

401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

---

See also

{{< page-relref ref="methods/push" caption="push API methods" >}}

{{< caption-link url="https://github.com/mastodon/mastodon/blob/main/app/controllers/api/v1/notifications_controller.rb" caption="app/controllers/api/v1/notifications_controller.rb" >}}