--- title: Notifications and mentions description: Read Bluesky and LinkedIn organization notifications, plus native mention timelines on X, Instagram, and Threads, with cursors and scopes. --- Bluesky and LinkedIn implement the normalized notifications facade. LinkedIn covers organization pages only. X, Instagram, and Threads have no notifications API, so their adapters declare `notifications.read` as `unsupported-by-platform` and expose native mention reads instead. YouTube and TikTok have neither. ## Normalized API ```ts social.notifications.list(account, { cursor?, limit? }, options?) social.notifications.iterate(account, { limit?, maxPages?, maxItems? }, options?) social.notifications.markSeen(account, { seenAt? }, options?) ``` `list` returns `Page` with `items` and optional opaque `nextCursor`. Pass that cursor unchanged to the next `list` call. `iterate` follows cursors lazily within its bounds. `markSeen` returns `void`; `notifications.read` and `notifications.seen` are separate capabilities. Objects stay provider-shaped. The examples assume one `social` client built with the platform's adapter and an `account` from `connectedAccountRef`. `accountId` is the Bluesky DID, the LinkedIn organization URN, the X or Threads user ID, or the Instagram account ID. Native calls also take the `context` your application passes to adapter operations. ## Platform support ### Bluesky **Normalized** `list`, `iterate`, and `markSeen`. Needs an access JWT or OAuth session with `repo`. Paging uses the AT Protocol cursor. Configure `bluesky({ auth: { service, did, accessJwt } })`, or pass an OAuth `session` instead of `accessJwt`. The adapter calls `app.bsky.notification.listNotifications` and the seen endpoint. Reasons include `like`, `repost`, `follow`, `mention`, and `reply`. ```ts const page = await social.notifications.list(account, { limit: 50 }); await social.notifications.markSeen(account, { seenAt: new Date().toISOString() }); ``` ### LinkedIn **Normalized** `list` and `iterate` for organization accounts. Needs the Community Management API product, `rw_organization_admin`, and an administrator role on the organization. `markSeen` is not supported. Configure `linkedin({ auth: { accessToken, author: "urn:li:organization:123" }, apiVersion })`. The adapter calls `organizationalEntityNotifications` with all seven action types: `LIKE`, `COMMENT`, `SHARE`, `SHARE_MENTION`, `ADMIN_COMMENT`, `COMMENT_EDIT`, and `COMMENT_DELETE`. Items keep `notificationId`, `action`, `sourcePost`, `generatedActivity`, and `lastModifiedAt`. ```ts const page = await social.notifications.list(account, { limit: 50 }); ``` Page sizes run from 1 to 100 and the cursor is an offset. LinkedIn keeps notifications for 60 days and recommends webhooks for ongoing delivery. Member accounts declare `notifications.read` as `account-ineligible`. ### X **Native** `mentions` only. X API v2 has no notifications list endpoint. The Account Activity API and X Activity API push events to webhooks or streams, which this read does not cover. Needs a user access token with `mentions.read`. Subject to X API paging and rate limits. Configure `x({ auth: { userId, accessToken } })` and use the X user ID as `accountId`. The method calls `GET /2/users/:id/mentions` and returns a `Page` of X posts. ```ts const native = social.native("default", { acknowledgeUnsafe: true }); const page = await native.mentions({ account, limit: 50, context }); ``` Pass `page.nextCursor` back as `cursor`. A missing user token or scope raises `missing_permission` or `unauthorized`. ### Instagram **Native** `listMentions` (also exposed as `mentions`). Works with Instagram Login and Facebook Login. Instagram Login needs `instagram_business_basic` and `instagram_business_manage_comments`. Facebook Login needs `instagram_basic`, `instagram_manage_comments`, and `pages_read_engagement`. Configure `instagram({ auth: { accountId, accessToken } })` for Instagram Login, or add `flavor: "facebook-login"`. The adapter reads the `/{ig-user-id}/tags` edge on the matching Graph host and returns tagged-media objects with a cursor. Meta does not return private media or Story mentions. ```ts const native = social.native("default", { acknowledgeUnsafe: true }); const page = await native.listMentions({ account, limit: 50, context }); ``` `mentionedMedia` and `mentionedComment` look up one caption or comment mention by ID and need Facebook Login. Meta documents no Instagram Login equivalent, so with Instagram Login they raise `unsupported_capability` before any request. ### Threads **Native** `mentions` only. The Threads API has no notifications endpoint. Needs `threads_basic` and `threads_manage_mentions`. Configure `threads({ auth: { userId, accessToken } })`. The method calls the `/:threads-user-id/mentions` edge and returns the provider JSON unchanged. ```ts const native = social.native("default", { acknowledgeUnsafe: true }); const page = await native.mentions({ account, context }); ``` Store the provider cursor and pass it as `cursor` on the next call. The provider reports missing permissions as `unauthorized` or an upstream error. ### YouTube **Not supported.** The YouTube Data API has no notifications resource. `activities.list` reports actions a channel took, not notifications it received. The adapter declares `notifications.read` as `unsupported-by-platform` and has no native mentions method. A normalized call raises `SocialError` with `code: "unsupported_capability"`. ```ts const { capabilities } = social.capabilities().default; const canRead = capabilities.some( (c) => c.operation === "notifications.read" && c.availability === "available", ); ``` ### TikTok **Not supported.** TikTok for Developers APIs expose no notification inbox or mentions read. The adapter declares `notifications.read` as `unsupported-by-platform`, and a normalized call raises `unsupported_capability`. ## Errors Calling the normalized notifications facade for X, Instagram, Threads, YouTube, TikTok, or a LinkedIn member account raises `unsupported_capability` before any request. So does `markSeen` on LinkedIn. Invalid page limits raise `invalid_input`. Native calls bypass tenant authorization and concurrency middleware, so apply your own policy around them. Sources, accessed 2026-09-24: [LinkedIn organization social action notifications](https://learn.microsoft.com/en-us/linkedin/marketing/community-management/organizations/organization-social-action-notifications), [X Activity API](https://docs.x.com/x-api/activity/introduction), [X Account Activity API](https://docs.x.com/x-api/account-activity/introduction), [Threads API reference](https://developers.facebook.com/docs/threads/reference), [Instagram IG User reference](https://developers.facebook.com/docs/instagram-platform/instagram-graph-api/reference/ig-user), [YouTube Data API reference](https://developers.google.com/youtube/v3/docs), [TikTok for Developers overview](https://developers.tiktok.com/doc/overview).