# rc.retrieveProjectCandidates

Read the candidates in a LinkedIn Recruiter Lite project's pipeline, from all stages or from one, with each candidate's stage.

> 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 the candidates in the pipeline of a LinkedIn Recruiter Lite project, from all stages or from one stage, with the stage each candidate is in.

The account needs a Recruiter Lite seat, Linked API's Plus plan and a [supported LinkedIn interface language](/docs/recruiter-lite-overview#seat-requirements) – see [Recruiter Lite](/docs/recruiter-lite-overview). To find a project's ID, call [rc.retrieveProjects](/docs/action-rc-retrieve-projects).

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

:::surface cli
The command is `linkedin recruiter projects candidates`. Its argument and flags are listed below.
:::

## Constraints

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

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

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

## Parameters

```json tab=HTTP
{
  "actionType": "rc.retrieveProjectCandidates",
  "label": "pipeline",
  "projectId": "1700000001",
  "stage": "uncontacted",
  "limit": 100
}
```

```typescript tab=Node
const workflow = await linkedapi.rcRetrieveProjectCandidates.execute({
  projectId: "1700000001",
  stage: "uncontacted",
  limit: 100
});

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

```python tab=Python
from linkedapi import RcRetrieveProjectCandidatesParams

workflow = linkedapi.rc_retrieve_project_candidates.execute(
    RcRetrieveProjectCandidatesParams(
        project_id="1700000001",
        stage="uncontacted",
        limit=100,
    )
)

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

```bash tab=CLI
linkedin recruiter projects candidates 1700000001 \
  --stage uncontacted \
  --limit 100 \
  --json
```

In AI assistants, the MCP tool is `rc_retrieve_project_candidates`. The n8n action is **Retrieve project candidates in Recruiter Lite**; the Make module is **Retrieve Project Candidates in Recruiter Lite**.

| Parameter | Description |
| --- | --- |
| `label` | Optional. Label included in workflow completion. |
| `projectId` | Required. Project ID, a string of digits, from [rc.retrieveProjects](/docs/action-rc-retrieve-projects) or [rc.createProject](/docs/action-rc-create-project). |
| `stage` | Optional. Read only this stage: `uncontacted`, `contacted`, `replied` or `archived`. Omit it to read all stages. |
| `limit` | Optional. Number of candidates to return, from 1 to 1000. Defaults to 25. |

:::surface cli
| Arg | Required | Description |
| --- | --- | --- |
| `project-id` | yes | Project ID, from `linkedin recruiter projects` or `linkedin recruiter projects create` |

| Flag | Description |
| --- | --- |
| `--stage` | Read only this stage: `uncontacted`, `contacted`, `replied` or `archived`. Omit it to read all stages. |
| `--limit` | Number of candidates to return, 1–1000; default 25. |
:::

## Reading behaviour

- **Pages.** The action reads the pipeline page by page until it has `limit` candidates or the pipeline ends. If a page does not change after its Next click, or still shows the previous rows, the action fails rather than return a short list.
- **Empty.** An empty project, or an empty stage, succeeds with an empty `data` array.
- **No limit category.** Reading a pipeline does not open profiles and does not count against `rcPersonProfileViews`.

## Result options

1. **Successful reading:**

```json
{
  "actionType": "rc.retrieveProjectCandidates",
  "label": "pipeline",
  "success": true,
  "data": [
    {
      "name": "Jane Example",
      "recruiterProfileUrl": "https://www.linkedin.com/talent/profile/AEMAAB0xExampleProfileId1",
      "headline": "Data Engineer at Example Logistics",
      "location": "Amsterdam, North Holland, Netherlands",
      "avatarUrl": null,
      "viewerState": { "connectionDegree": "2nd" },
      "stage": "uncontacted"
    }
  ]
}
```

| Field | Meaning |
| --- | --- |
| `name` | Candidate's full name. |
| `recruiterProfileUrl` | Candidate's Recruiter profile, `https://www.linkedin.com/talent/profile/…`, without query parameters. Pass it as `personUrl` to [rc.openPersonPage](/docs/action-rc-open-person-page). |
| `headline` | Headline as the pipeline shows it, or an empty string. |
| `location` | Location as the pipeline shows it, or an empty string. |
| `avatarUrl` | Profile photo URL, or `null` without a photo. |
| `viewerState.connectionDegree` | `1st`, `2nd` or `3rd+`, or `null` when Recruiter shows none. |
| `stage` | The candidate's stage in this project: `uncontacted`, `contacted`, `replied` or `archived`. |

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

2. **Failed reading:**

```json
{
  "actionType": "rc.retrieveProjectCandidates",
  "label": "pipeline",
  "success": false,
  "error": {
    "type": "projectNotFound",
    "message": "The Recruiter project could not be opened or no longer exists."
  }
}
```

Possible `error.type` values:

- `projectNotFound` – the seat cannot open a project with this ID: Recruiter answers with its page-not-found.
- `recruiterSignInRequired`, `recruiterTwoStepVerificationRequired`, `recruiterMultipleSessionsDetected` – the seat needs attention, see [account errors](/docs/recruiter-lite-overview#account-errors).
- `unexpectedError` – the pipeline could not be read completely.
