# nv.retrieveListLeads

Retrieve the leads in one of your Sales Navigator lead lists, with the URLs used to open, save or remove them.

> 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.

Retrieve the leads in one of your Sales Navigator lead lists. For example, export a list to your CRM, or check who is in it before removing someone with [`nv.removeLeadFromList`](/docs/action-nv-remove-lead-from-list). Each lead's `hashedUrl` can be passed straight to [`nv.openPersonPage`](/docs/action-nv-open-person-page), [`nv.saveLead`](/docs/action-nv-save-lead) or [`nv.removeLeadFromList`](/docs/action-nv-remove-lead-from-list).

An active Sales Navigator subscription is required. To find a list's ID, call [`nv.retrieveLists`](/docs/action-nv-retrieve-lists) with `type` set to `lead`. For the companies in an account list, use [`nv.retrieveListAccounts`](/docs/action-nv-retrieve-list-accounts).

:::surface node,python
In the SDK this is the `nvRetrieveListLeads` method. It takes the parameters below except `label`, which exists only in workflow JSON. The result below is returned in `data`.
:::

:::surface cli
The command is `linkedin navigator lists leads`. Its argument and flag are listed below.
:::

## Constraints

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

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

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

## Parameters

```json tab=HTTP
{
  "actionType": "nv.retrieveListLeads",
  "label": "emeaLeads",
  "listId": "7420000000000000001",
  "limit": 100
}
```

```typescript tab=Node
const workflow = await linkedapi.nvRetrieveListLeads.execute({
  listId: "7420000000000000001",
  limit: 100
});

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

```python tab=Python
from linkedapi import NvRetrieveListLeadsParams

workflow = linkedapi.nv_retrieve_list_leads.execute(
    NvRetrieveListLeadsParams(
        list_id="7420000000000000001",
        limit=100,
    )
)

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

```bash tab=CLI
linkedin navigator lists leads 7420000000000000001 --limit 100 --json
```

In AI assistants, the MCP tool is `nv_retrieve_list_leads`. The n8n action is **Retrieve list leads in Sales Navigator**; the Make module is **Retrieve List Leads in Sales Navigator**.

| Parameter | Description |
| --- | --- |
| `label` | Optional label included in workflow completion. |
| `listId` | Required. ID of one of your lead lists, as returned in `id` by [`nv.retrieveLists`](/docs/action-nv-retrieve-lists) or [`nv.createList`](/docs/action-nv-create-list). Pass it as a string; a number is rejected. |
| `limit` | Optional. Maximum number of leads to return, from 1 to 1000. Defaults to 25. |

Invalid parameters are rejected with `invalidWorkflow` before the workflow starts.

:::surface cli
| Arg | Required | Description |
| --- | --- | --- |
| `list-id` | yes | ID of one of your lead lists |

| Flag | Description |
| --- | --- |
| `--limit` | Maximum number of leads to return, 1–1000; default 25. |
:::

## Reading behaviour

- **Only your own lead lists.** `listId` must be one of the lead lists [`nv.retrieveLists`](/docs/action-nv-retrieve-lists) returns for you. An account list's ID, a list someone else shared with you, or an ID that is not one of your lists fails with `listNotFound`.
- **In Sales Navigator's order, up to `limit`.** Leads are returned in the order the list shows them. Linked API reads the list 25 leads at a time until it has `limit` leads or reaches the end of the list. An empty list returns an empty array.
- **Ready for other actions.** `urn` and `hashedUrl` have the same form as in [`nv.searchPeople`](/docs/action-nv-search-people). Pass `hashedUrl` to [`nv.openPersonPage`](/docs/action-nv-open-person-page), [`nv.saveLead`](/docs/action-nv-save-lead) or [`nv.removeLeadFromList`](/docs/action-nv-remove-lead-from-list), or to `filter.subjects` in [`nv.retrieveAlerts`](/docs/action-nv-retrieve-alerts#alerts-for-a-list-or-for-chosen-subjects).
- **Recent changes can take tens of seconds to appear.** Right after a lead is added to or removed from the list, this action can still return the list as it was. Read it again a little later.
- **A list that changes while it is read.** If the list changes between two of its pages, the call fails with `unexpectedError` rather than returning a partial or repeated list. Call it again.

## Result options

```json
{
  "actionType": "nv.retrieveListLeads",
  "label": "emeaLeads",
  "success": true,
  "data": [
    {
      "name": "Jane Smith",
      "urn": "urn:li:member:123456789",
      "hashedUrl": "https://www.linkedin.com/in/SInQBmjJ015eLr8",
      "position": "Head of Sales",
      "companyName": "Example Labs",
      "location": "London, England, United Kingdom",
      "addedToListAt": "2026-10-30T09:00:00.000Z"
    },
    {
      "name": "Tom Brown",
      "urn": "urn:li:member:987654321",
      "hashedUrl": "https://www.linkedin.com/in/ACoAA2DdsSV83B48",
      "position": null,
      "companyName": null,
      "location": "Berlin, Germany",
      "addedToListAt": "2026-10-28T14:30:00.000Z"
    }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `name` | The lead's full name. |
| `urn` | [URN](/docs/data-conventions#linkedin-urns) of the person, `urn:li:member:<id>`. |
| `hashedUrl` | [Hashed](/faq/what-are-hashed-url-and-public-url) LinkedIn URL of the person. |
| `position` | Title of the lead's current position, or `null`. |
| `companyName` | Company of the lead's current position, or `null`. |
| `location` | The lead's location, or `null`. |
| `addedToListAt` | When the lead was added to this list, in ISO 8601 UTC, or `null` when Sales Navigator does not report it. This is the list membership time, not the time the lead was saved. |

`label` is included only if specified in the action parameters.

## Error result

An unsuccessful action returns `success: false` with an `error` object:

```json
{
  "actionType": "nv.retrieveListLeads",
  "label": "emeaLeads",
  "success": false,
  "error": {
    "type": "listNotFound",
    "message": "The list is not available for this subject in Sales Navigator."
  }
}
```

Possible `error.type` values:

- `noSalesNavigator` — the account does not have an active Sales Navigator subscription.
- `listNotFound` — `listId` is not one of your lead lists. This includes an account list's ID and a list someone else shared with you.
- `unexpectedError` — the list could not be read, for example because it changed while it was being read. Call it again.