> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/endpoints/list
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# Get a List

> Retrieve a List with its member and Pending Intake counts and a page of stored rows, filtered by kind, with cursor pagination at no credit cost.

- Endpoint: `GET https://api.reversecontact.com/v2/lists/:listId`
- Credits: Free.
- Answer: synchronous.
- Available in: REST API, MCP tool `get_list`, TypeScript and Python SDKs.
- Last verified: 2026-11-04

## Introduction

The Get a List endpoint returns one List and one page of its rows, ordered by the date they were added: the List Members (`kind: "member"`) and the lines no one matched, kept as [Pending Intake](https://docs.reversecontact.com/guides/lists#pending-intake) (`kind: "pending"`). It reads what the List already holds and never looks anyone up.

This endpoint is **free** (0 credits). It counts toward your per-minute rate limit like any other call. To page through the rows without the List header, or to find members by your own identifier, use [List members](https://docs.reversecontact.com/endpoints/list-members).

The API key needs the `lists` permission (see [API key management](https://docs.reversecontact.com/guides/api-key-management)).

## Authorization

| Name     | Type   | Required | Description                                                                                         |
| -------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| `apikey` | string | Yes      | Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header. |

## Request

The route is `GET /v2/lists/:listId`.

### Path parameters

| Name     | Type   | Required | Description    |
| -------- | ------ | -------- | -------------- |
| `listId` | string | Yes      | List id (UUID) |

### Query Parameters

| Name      | Type    | Required | Description                                                                                                         |
| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `kind`    | string  | No       | `all` (default) mixes members and Pending Intake by added date, `members` or `pending` returns one kind only        |
| `perPage` | integer | No       | Rows per page, from 1 to 1,000. Defaults to 100.                                                                    |
| `cursor`  | string  | No       | The `nextCursor` of the previous page, sent with the same `kind`. A malformed cursor, or one sent with other parameters, returns `400`. |

## Response structure

| Field     | Type    | Description                                      |
| --------- | ------- | ------------------------------------------------ |
| `success` | boolean | `true` if the request was processed successfully |
| `error`   | `null`  | Always `null` on success                         |

**data** (ListDetail): The List and one page of its rows

| Field        | Type           | Description                                                          |
| ------------ | -------------- | -------------------------------------------------------------------- |
| `list`       | object         | The List, with the fields of [All Lists](https://docs.reversecontact.com/endpoints/lists#response-structure) |
| `members`    | array          | One page of rows: members (`kind: "member"`) and Pending Intake (`kind: "pending"`). Each row is described in [List members](https://docs.reversecontact.com/endpoints/list-members#response-structure). |
| `nextCursor` | string \| null | Send it back as `cursor` for the next page, `null` on the last page  |

`quotas` and `metadata` are the blocks of every V2 response: see [Usage](https://docs.reversecontact.com/endpoints/usage#response-structure).

A List that does not exist in your workspace returns `404 LIST_NOT_FOUND`, or `404 LISTS_NOT_ACTIVATED` when the workspace has never had a List.

## Code examples

**Code Examples**

```bash [cURL]
curl "https://api.reversecontact.com/v2/lists/3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40?perPage=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```javascript [JavaScript]
const listId = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40";
const response = await fetch(
  `https://api.reversecontact.com/v2/lists/${listId}?perPage=50`,
  { headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);

const { data } = await response.json();
console.log(data.list.name, `${data.list.memberCount} members`);
console.log("Rows on this page:", data.members.length);
```
```python [Python]
import requests

list_id = "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40"
response = requests.get(
    f"https://api.reversecontact.com/v2/lists/{list_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"perPage": 50}
)

data = response.json()["data"]
print(data["list"]["name"], f"{data['list']['memberCount']} members")
```

## Example response

**Example Response**

```json [200 - Success]
{
  "success": true,
  "data": {
    "list": {
      "id": "3f6c2a8e-1b4d-4f0a-9c7e-5d2b8a1e6f40",
      "name": "Q4 sales leaders",
      "entity": "persons",
      "memberCount": 2,
      "pendingIntakeCount": 1,
      "revision": 3,
      "archivedAt": null,
      "createdAt": "2026-10-28T09:12:44.000Z",
      "updatedAt": "2026-10-28T09:20:02.000Z",
      "originQuery": null,
      "originLastFind": null
    },
    "members": [
      {
        "kind": "member",
        "id": "9b1e4c7a-2d3f-4e8a-b6c5-0a1f2e3d4c5b",
        "entityId": "prs_01jbd5vewyenebxgaz869ffe5t",
        "linkedinUrl": "https://www.social.com/in/janedoe",
        "status": "enriched",
        "fields": {
          "name": "Jane Doe",
          "headline": "VP Sales at Acme Corp",
          "company": "Acme Corp",
          "location": { "country": "France" },
          "url": "https://www.social.com/in/janedoe",
          "status": "enriched"
        },
        "addedAt": "2026-10-28T09:15:31.000Z",
        "families": {
          "profile": { "enrichedAt": "2026-10-28T09:15:31.000Z" }
        },
        "externalId": "crm-001"
      },
      {
        "kind": "pending",
        "id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
        "signal": { "email": "unknown.person@example.com" },
        "source": "paste",
        "addedAt": "2026-10-28T09:15:32.000Z",
        "fields": {}
      }
    ],
    "nextCursor": null
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": { "total": 10000, "used": 4521, "left": 5479 }
    }
  },
  "metadata": {
    "requestId": "2313f06e-20b2-4452-8f83-5987f4c420c8",
    "executionTimeMs": 44
  }
}
```