# List notifications

```{raw} html
<div class="mo-api-page-show-toc" aria-hidden="true"></div>
```

List the current user’s notifications and read status.

```text
GET https://billing.moi.matrixorigin.cn/api/v1/taas/notifications
```

## Before you begin

Prepare a personal access token. For creation and management, see [Manage personal access tokens](../../../../../guides/billing/credentials.md#personal-access-token).

Results are scoped to data accessible to the current user.

## Query parameters

Replace `$MOI_PERSONAL_ACCESS_TOKEN` in the example with your personal access token.

:::::::{div} mo-api-tabs
::::::{tab-set}
:::::{tab-item} Request example

```bash
curl --get "https://billing.moi.matrixorigin.cn/api/v1/taas/notifications" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN" \
  --data-urlencode "page_size=2"
```

Save the returned `next_page_token` as `$NEXT_PAGE_TOKEN`, retain the same filters, and request the next page. Stop when this value is empty or omitted.

```bash
curl --get "https://billing.moi.matrixorigin.cn/api/v1/taas/notifications" \
  -H "X-API-Key: $MOI_PERSONAL_ACCESS_TOKEN" \
  --data-urlencode "page_size=2" \
  --data-urlencode "page_token=$NEXT_PAGE_TOKEN"
```

:::::
:::::{tab-item} Parameters

::::{div} mo-api-parameter-table

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `category` | string | No | Category: usage, key, call, `security`, or service. |
| `priority` | string | No | Priority: `severe`, `important`, or normal. |
| `read` | string | No | Read filter: `true` or `false`; omit for both. |
| `time_range` | string | No | Time range: all, `today`, 7d, or 30d; defaults to 7d. `today` starts at midnight in the server time zone. |
| `page_size` | integer | No | Page size; default 100, maximum 1000. |
| `page_token` | string | No | Next-page token from the previous response; omit for the first request. |

::::

:::::
::::::
:::::::

## Successful response

Returns HTTP `200` with the current page of notifications and pagination information.

:::::::{div} mo-api-tabs mo-api-response-tabs
::::::{tab-set}
:::::{tab-item} Response example

```json
{
  "items": [],
  "total": 0,
  "next_page_token": ""
}
```

:::::
:::::{tab-item} Fields

| Field | Type | Description |
| --- | --- | --- |
| `items` | array of object | Records on this page. |
| `items[].id` | string | Notification ID. |
| `items[].user_id` | string | Owning user ID. |
| `items[].rule_key` | string | Identifier of the triggering rule. |
| `items[].category` | string | Notification category. |
| `items[].priority` | string | Priority: `severe`, `important`, or normal. |
| `items[].title` | string | Notification title. |
| `items[].summary` | string | Notification summary. |
| `items[].state` | string | Notification state. |
| `items[].scope_type` | string | Related object type, when present. |
| `items[].scope_id` | string | Related object ID, when present. |
| `items[].scope_name` | string | Related object name, when present. |
| `items[].source_type` | string | Notification source type, when present. |
| `items[].source_id` | string | Notification source ID, when present. |
| `items[].action_url` | string | Related action URL, when present. |
| `items[].fingerprint` | string | Notification event fingerprint, when present. |
| `items[].seq` | integer | Notification sequence number. |
| `items[].read` | boolean | Whether the notification has been read. |
| `items[].occurred_at` | integer | Event time, Unix seconds. |
| `items[].created_at` | integer | Creation time, Unix seconds. |
| `items[].updated_at` | integer | Update time, Unix seconds. |
| `total` | integer | Total records matching the filters. |
| `next_page_token` | string | Next-page token; empty or omitted on the last page. |

In field paths, `[]` denotes each array item.

:::::
::::::
:::::::