# nv.retrieveAlerts

Retrieve Sales Navigator lead and account alerts with filters and sorting.

> The API Reference is also the SDK and CLI reference. Consecutive code fences marked `tab=HTTP`, `tab=Node`, `tab=Python` and `tab=CLI` are the same call on each surface (a fence marked `tab=HTTP,CLI` is the same text for both), and a block between `:::surface <names>` and `:::` applies only to the surfaces it names. Identifiers in the text are written as in Node and in HTTP JSON (camelCase); the Python SDK spells methods, parameters and result attributes in snake_case (`sendMessage` → `send_message`, `reconnectionLink` → `reconnection_link`), while names inside HTTP JSON stay camelCase.

Read lead and account alerts from your Sales Navigator home feed. Use the alert's type and timestamp to decide when to reach out, then open its subject with [`nv.openPersonPage`](/docs/action-nv-open-person-page) or [`nv.openCompanyPage`](/docs/action-nv-open-company-page).

An active Sales Navigator subscription is required. By default, the action includes saved and unsaved subjects, as well as subjects with unknown saved state. Set `filter.excludeSuggested` to `true` to return only subjects confirmed as saved. This excludes all unsaved and unknown-state subjects, including alerts without a "Suggested" label in Sales Navigator.

:::surface node,python
The SDK method is `nvRetrieveAlerts` in Node and `nv_retrieve_alerts` in Python. The result below is returned in `data`.
:::

:::surface cli
The command is `linkedin navigator alerts`. Its flags are listed below.
:::

## Constraints

> ⏺️ **Root Start:** allowed.

> ⬆️ **Parent Actions:** N/A.

> ⬇️ **Child Actions:** N/A.

## Parameters

```json tab=HTTP
{
  "actionType": "nv.retrieveAlerts",
  "label": "companySignals",
  "limit": 50,
  "sort": "latest",
  "filter": {
    "category": "account",
    "types": ["ACCOUNT_SHARED_UPDATE", "ACCOUNT_SENIOR_HIRE"],
    "since": "2026-10-01T00:00:00Z",
    "excludeSuggested": false
  }
}
```

```typescript tab=Node
const workflow = await linkedapi.nvRetrieveAlerts.execute({
  limit: 50,
  sort: "latest",
  filter: {
    category: "account",
    types: ["ACCOUNT_SHARED_UPDATE", "ACCOUNT_SENIOR_HIRE"],
    since: "2026-10-01T00:00:00Z",
    excludeSuggested: false
  }
});

const { data, errors } = await linkedapi.nvRetrieveAlerts.result(workflow.workflowId);
```

```python tab=Python
from linkedapi import NvRetrieveAlertsParams

workflow = linkedapi.nv_retrieve_alerts.execute(
    NvRetrieveAlertsParams(
        limit=50,
        sort="latest",
        filter={
            "category": "account",
            "types": ["ACCOUNT_SHARED_UPDATE", "ACCOUNT_SENIOR_HIRE"],
            "since": "2026-10-01T00:00:00Z",
            "exclude_suggested": False,
        },
    )
)

result = linkedapi.nv_retrieve_alerts.result(workflow.workflow_id)
```

```bash tab=CLI
linkedin navigator alerts \
  --limit 50 \
  --sort latest \
  --category account \
  --types ACCOUNT_SHARED_UPDATE,ACCOUNT_SENIOR_HIRE \
  --since 2026-10-01T00:00:00Z \
  --json
```

In AI assistants, the MCP tool is `nv_retrieve_alerts`. The n8n action is **Retrieve alerts in Sales Navigator**; the Make module is **Retrieve Alerts in Sales Navigator**.

| Parameter | Description |
| --- | --- |
| `label` | Optional label included in workflow completion. |
| `limit` | Maximum matching alerts to return, from 1 to 1000. Defaults to 50. |
| `sort` | `latest` (default): newest first. `relevance`: Sales Navigator's main alert feed order, preserving relative order when filtering by category. |
| `filter.category` | Filter by `subject.type`: `lead` or `account`, consistently for both sort orders. Omit to retrieve both. Sales Navigator's tabs can group the same alerts differently. |
| `filter.types` | Exact machine codes from an alert's `type` field. Omit or pass an empty array for all types. |
| `filter.since` | Inclusive timestamp in extended ISO 8601 calendar format with a timezone, such as `2026-10-01T00:00:00Z`. Only alerts published at or after this time are included. |
| `filter.excludeSuggested` | Defaults to `false`: include saved, unsaved, and unknown-state subjects. Set to `true` to return only subjects confirmed as saved, whether or not the UI labels the excluded alerts as suggestions. |

All filter conditions are combined with AND. Values within `filter.types` are alternatives. The action reads additional feed pages when needed to find matching alerts; `limit` counts matches, not scanned records. Fewer matches, including an empty array, are a successful result when the available feed is exhausted.

For example, an accepted-invitation alert about an unsaved lead is included by default, even if Sales Navigator shows no "Suggested" label. Setting `filter.excludeSuggested: true` excludes it. Unknown saved state stays `null` and is included by default; it is excluded when `filter.excludeSuggested` is `true`, because it is not confirmation that the subject is saved.

:::surface cli
| Flag | Description |
| --- | --- |
| `--limit` | Maximum matching alerts, 1–1000; default 50. |
| `--sort` | `latest` or `relevance`; default `latest`. |
| `--category` | `lead` or `account`; omit for both. |
| `--types` | Comma-separated machine type codes. |
| `--since` | Inclusive ISO timestamp cutoff. |
| `--exclude-suggested` | Return only subjects confirmed as saved; excludes unsaved and unknown saved states. Defaults to `false`. |
:::

## Alert types

The `type` field preserves Sales Navigator's machine code. Types observed on the live feed include:

| Type | Signal |
| --- | --- |
| `LEAD_SHARED_UPDATE` | A lead shared a post or update. |
| `LEAD_ACCEPTED_INVITATION` | A lead accepted an invitation. |
| `LEAD_PROFILE_VIEW_SIGNAL` | A lead viewed your profile. |
| `ACCOUNT_SHARED_UPDATE` | A company shared a post or update. |
| `ACCOUNT_SENIOR_HIRE` | A company hired a senior decision maker. |
| `ACCOUNT_HEADCOUNT_ACCELERATED_FLOW` | Increased employee movement involving companies. |

This is an open set: other types can appear as Sales Navigator adds signals. Filter on codes returned in `type`, rather than matching the localized headline. A type filter with no matching alerts returns an empty array.

## Result options

```json
{
  "actionType": "nv.retrieveAlerts",
  "label": "companySignals",
  "success": true,
  "data": [
    {
      "id": "urn:li:notificationV2:example-alert",
      "type": "ACCOUNT_SHARED_UPDATE",
      "publishedAt": "2026-10-30T09:00:00.000Z",
      "subject": {
        "type": "account",
        "urn": "urn:li:fs_salesCompany:12345",
        "name": "Example Labs",
        "url": "https://www.linkedin.com/sales/company/12345",
        "saved": true
      },
      "headline": "Example Labs shared an update.",
      "text": "Meet our latest product update.",
      "subline": "Software Development",
      "url": "https://www.linkedin.com/feed/sales-navigator/urn:li:share:1234567890",
      "relatedEntityUrn": "urn:li:share:1234567890"
    }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `id` | Sales Navigator's opaque alert URN. Store it to recognize alerts returned by earlier retrievals. |
| `type` | Machine alert code, independent of interface language. |
| `publishedAt` | Exact publication timestamp supplied by Sales Navigator, in ISO 8601 UTC. |
| `subject.type` | `lead` or `account`. |
| `subject.urn` | The subject's Sales Navigator URN. |
| `subject.name` | Subject name, or `null` when matching identity metadata is unavailable. |
| `subject.url` | Subject URL usable with `nv.openPersonPage` or `nv.openCompanyPage`. |
| `subject.saved` | `true` or `false` when Sales Navigator supplies matching saved-state metadata; otherwise `null`. |
| `headline` | Alert headline in the account's interface language, or `null`. |
| `text` | Alert body or post text when supplied, otherwise `null`. |
| `subline` | Additional context supplied with the alert, or `null`. |
| `url` | Alert's destination URL, or `null`. It can point to a related person, post or search rather than the subject. |
| `relatedEntityUrn` | Related post, position or other entity named by the alert, or `null`. |

A lead's `subject.url` uses `/sales/lead/…`; an account's uses `/sales/company/…`. Subject metadata is associated by identity. When an alert describes several entities, a name or saved state belonging to another entity is not attached to the subject.

## Retrieval and history

Each call reads the feed currently available to your account. Linked API does not store alerts, track a polling cursor or send alert webhooks. To check for new alerts, call again with `filter.since` and deduplicate by `id`; the inclusive timestamp lets you retain events sharing the same publication time.

Sales Navigator controls which alerts remain available. `since` filters the available feed and does not recover expired or cleared alerts. No fixed history period is guaranteed. Saved-search email notifications and shared-list system notifications are outside this action's lead and account feed.

The action reads alerts without clearing, bookmarking or saving them. With `filter.excludeSuggested: true`, an account with no confirmed saved leads or accounts returns an empty result even when Sales Navigator shows suggestions. A missing or unreadable feed response is reported as a failure, not as an empty successful result.

Retrieval resets the home feed's filters and applies the requested sort. These view settings can remain selected when you next use Sales Navigator. Category filtering is applied to the returned subjects.

## Error result

An unsuccessful action returns `success: false` with an `error` object. Possible `error.type` values:

- `noSalesNavigator` — the account does not have an active Sales Navigator subscription.
- `unexpectedError` — the feed could not be retrieved or parsed.