get_notifications

Retrieve the authenticated user's notifications.

Authentication

Required: Yes (Private tool)

Parameters

`limit` (optional)

Type: number
Default: 50
Constraints: 1-100
Description: Maximum number of notifications to return

`cursor` (optional)

Type: string
Description: Pagination cursor from previous response

`seenAt` (optional)

Type: string
Description: ISO 8601 timestamp passed through to the read API to compute each notification's isRead flag relative to that time. This is a read-only parameter; it does not mark notifications as read or change server-side read state.

`countOnly` (optional)

Type: boolean
Default: false
Description: When true, return only the unread count and skip fetching the notification list — a cheap badge-number path. The response contains just { success, unreadCount }; the notifications, cursor, hasMore, and seenAt fields are omitted.

This tool is read-only: it lists notifications but never mutates server-side read state. To clear the unread state after processing, use the mark_notifications_seen tool.

Response

Tool results are returned as stringified JSON text. The shape below is illustrative.

When countOnly is true, only success and unreadCount are returned:

typescript

{
  success: boolean;
  unreadCount: number;
}

Otherwise the full list is returned (unreadCount is always present):

typescript

{
  success: boolean;
  unreadCount: number;  // Number of unread notifications
  notifications: Array<{
    uri: string;
    cid: string;
    author: {
      did: string;
      handle: string;
      displayName?: string;
      avatar?: string;
    };
    reason: string;  // "like", "repost", "follow", "mention", "reply", "quote"
    record: any;
    isRead: boolean;
    indexedAt: string;
    labels?: any[];
  }>;
  cursor?: string;
  seenAt?: string;
  hasMore: boolean;
}

Examples

Get Recent Notifications

json

{
  "limit": 50
}

Get Only the Unread Count

json

{
  "countOnly": true
}

Response:

json

{
  "success": true,
  "unreadCount": 7
}