> For the complete documentation index, see [llms.txt](https://mastodon.gitbook.io/mastodon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mastodon.gitbook.io/mastodon/methods/notifications.md).

# notifications

## Get all notifications

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/notifications`

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.\
\
**Returns:** Array of Notification\
**OAuth:** User token + `read:notifications`\
**Version history:**\
0.0.0 - added\
2.6.0 - add min\_id\
2.9.0 - add account\_id

#### Query Parameters

| Name           | Type   | Description                                                                    |
| -------------- | ------ | ------------------------------------------------------------------------------ |
| max\_id        | string | Return results older than this ID                                              |
| since\_id      | string | Return results newer than this ID                                              |
| min\_id        | string | Return results immediately newer than this ID                                  |
| limit          | string | Maximum number of results to return (default 20)                               |
| exclude\_types | array  | Array of types to exclude (`follow`, `favourite`, `reblog`, `mention`, `poll`) |
| account\_id    | string | Return only notifications received from this account                           |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Sample call with limit=2. Use the Link header for pagination" %}

```javascript
Link: <https://mastodon.social/api/v1/notifications?max_id=34975535>; rel="next", <https://mastodon.social/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",
        ...
      }
    }
  }
]
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

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

{% endtab %}
{% endtabs %}

## Get a single notification

<mark style="color:blue;">`GET`</mark> `https://mastodon.example/api/v1/notifications/:id`

View information about a notification with a given ID.\
\
**Returns:** Notification\
**OAuth:** User token + `read:notifications`\
**Version history:**\
0.0.0 - added

#### Path Parameters

| Name | Type   | Description                             |
| ---- | ------ | --------------------------------------- |
| :id  | string | ID of the notification in the database. |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 A single Notification" %}

```javascript
{
  "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"
      }
    ],
    ...
  }
},
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

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

{% endtab %}
{% endtabs %}

## Dismiss all notifications

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/notifications/clear`

Clear all notifications from the server.\
\
**Returns:** empty object\
**OAuth:** User token + `write:notifications`\
**Version history:**\
0.0.0 - added

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Notifications successfully cleared" %}

```javascript
{}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

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

{% endtab %}
{% endtabs %}

## Dismiss a single notification

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/notifications/:id/dismiss`

Clear a single notification from the server.\
\
**Returns:** empty object\
**OAuth:** User token + `write:notifications`\
**Version history:**\
1.3.0 - added

#### Path Parameters

| Name | Type   | Description                          |
| ---- | ------ | ------------------------------------ |
| :id  | string | ID of the notification to be cleared |

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

{% tabs %}
{% tab title="200 Notification with given ID successfully dismissed" %}

```javascript
{}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

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

{% endtab %}
{% endtabs %}

## (DEPRECATED) Dismiss a single notification

<mark style="color:green;">`POST`</mark> `https://mastodon.example/api/v1/notifications/dismiss`

Delete a single notification from the server.\
\
**Returns:** empty object\
**OAuth:** User token + `write:notifications`\
**Version history**:\
0.0.0 - available\
3.0.0 - removed

#### Headers

| Name          | Type   | Description          |
| ------------- | ------ | -------------------- |
| Authorization | string | Bearer \<user token> |

#### Request Body

| Name | Type   | Description                                                 |
| ---- | ------ | ----------------------------------------------------------- |
| id   | string | ID of the notification to be cleared, passed as a parameter |

{% tabs %}
{% tab title="200 Notification with given ID successfully dismissed" %}

```javascript
{}
```

{% endtab %}

{% tab title="401 Invalid or missing Authorization header" %}

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

{% endtab %}
{% endtabs %}