# List notifications

> Your notifications: one thread for each thing you were told about (an issue, a pull request, a workflow on a branch, a deployment), latest activity first.

<div class="g1t-endpoint"><span class="g1t-method" data-method="get">GET</span><code>/notifications</code></div>

As in your inbox, only unread threads unless `all` is true; `view` `saved` or `done` lists those instead, read or not. Each thread has a `reason`, why you were told (`agent`, `review_requested`, `assign`, `mention`, `ci_activity`, `security_alert`, `state_change`, `author`, `comment`, `manual` or `subscribed`), a `severity`, the latest activity's `title`, and `count`, how many things have happened on it. Filter by `reason` or `severity`, by `participating` (leaving out what you only watch or subscribed to by hand), by `since` and `before` (RFC 3339, the latest activity), or to one repository. A page holds `per_page` threads, 30 unless you say (at most 100); pass `next` back as `cursor` for the next. Threads about repositories you can no longer read are left out. Your own: a personal access token or a session, never a workspace's.

Unread threads only, unless `all=true`. Threads that wait on you (an agent, or a review asked of you) have severity `warning`.

| `reason` | You were told because |
| --- | --- |
| `agent` | An agent is waiting on you: it asked a question, or g1t stopped until a person steps in |
| `review_requested` | You were asked to review |
| `assign` | You were assigned |
| `mention` | Someone mentioned you by `@username` |
| `ci_activity` | Checks, a workflow or a deployment on your work finished |
| `security_alert` | A security alert on a repository you look after |
| `state_change` | It was closed, reopened or merged |
| `author` | You opened it, or asked g1t for it |
| `comment` | You commented on it |
| `manual` | You subscribed to it by hand |
| `subscribed` | You watch its repository |

With `participating=true`, threads you only follow (`manual`, `subscribed`) are left out. For the next page, pass `next` as `cursor`; `next` is null on the last.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`notifications`](/reference/mcp/#notifications) with `action` `list`, and the same inputs
- **Scope:** An access token needs [`notifications:read`](/guides/authentication/#scopes).
- **Also at:** [`GET /repos/{owner}/{name}/notifications`](/reference/api/notifications/list-repo-notifications/)

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `all` | boolean | No | Read threads too. Left out: only unread ones, in the inbox view. |
| `participating` | boolean | No | Only threads you take part in: not those you only watch or subscribed to by hand. |
| `view` | string | No | inbox (the default): not done and not snoozed. saved: what you saved. done: what you marked done. One of `inbox`, `saved`, `done`. |
| `reason` | string | No | Only threads you were told of for this reason. One of `agent`, `review_requested`, `assign`, `mention`, `team_mention`, `ci_activity`, `security_alert`, `state_change`, `author`, `comment`, `manual`, `subscribed`. |
| `severity` | string | No | Only threads of this severity. warning is what is waiting on you: an agent, or a review. One of `error`, `warning`, `success`, `info`. |
| `since` | string | No | RFC 3339: only threads with activity at or after this time. |
| `before` | string | No | RFC 3339: only threads whose latest activity was before this time. |
| `cursor` | string | No | The next page: the `next` of the page before. |
| `per_page` | integer | No | Threads a page: 30 unless you say, at most 100. |

## Example request

```sh
curl "https://api.g1t.sh/notifications?participating=true" \
  -H "Authorization: Bearer $G1T_TOKEN"
```

## Example response

A successful request answers `200` with:

```json
{
  "items": [
    {
      "id": "ntf_01kp7m2q3r4s5t6v7w8x9y0z1a",
      "reason": "review_requested",
      "severity": "warning",
      "title": "ada asked you to review flagon-io/hello#14",
      "body": "Add a greeting to the README",
      "event": "pull.review_requested",
      "repo": "flagon-io/hello",
      "workspace": "flagon-io",
      "subject": "pull",
      "number": 14,
      "url": "/flagon-io/hello/pull/14",
      "actor": "ada",
      "count": 3,
      "created_at": "2026-10-06T15:02:11.000Z",
      "updated_at": "2026-10-07T09:41:30.000Z",
      "read_at": null,
      "done_at": null,
      "saved": false,
      "snoozed_until": null
    },
    {
      "id": "ntf_01kp7k9a8b7c6d5e4f3g2h1j0k",
      "reason": "ci_activity",
      "severity": "error",
      "title": "Production of hello failed to deploy",
      "body": "The build failed: npm run build exited with 1.",
      "event": "deployment.failed",
      "repo": "flagon-io/hello",
      "workspace": "flagon-io",
      "subject": "deploy",
      "number": null,
      "url": "/flagon-io/hello/deployments/dpl_01kp7k8z7y6x5w4v3t2s1r0q9p",
      "actor": "syntaqx",
      "count": 1,
      "created_at": "2026-10-07T08:12:40.000Z",
      "updated_at": "2026-10-07T08:12:40.000Z",
      "read_at": null,
      "done_at": null,
      "saved": false,
      "snoozed_until": null
    }
  ],
  "next": null
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |