---
title: "Get a list"
method: GET
path: "/v2/lists/{id}"
tags: ["Lists"]
---

# Get a list

`GET /v2/lists/{id}`

## Request

- Base URL: `https://api.village.ai`
- URL: `https://api.village.ai/v2/lists/{id}`
- Auth: HTTP bearer

Get a list with all its items. Accepts EITHER the numeric list id or the list's public identifier (e.g. "fintech-8f3k2"), and what comes back follows which one you used. Numeric id: the owner view — every field, and you must own the list. Public identifier: the published view, readable by anyone once the owner has published it, carrying names, titles, companies, screening scores and the per-criterion breakdown, but never connection paths, introducer identities, contact details or warmth. On a public read, `id` is null unless you own the list, and item `id`s are absent. Items are sorted by connection strength (warmth score) on the owner view. Supports cursor pagination via `cursor` and `limit`.

## Path parameters

- `id` string, required: List ID

## Query parameters

- `cursor` string: Opaque cursor for items pagination (from previous response)
- `limit` string: Number of items per page (max 100)

## Response `200`

List retrieved successfully

- object
  - `data` ListWithItemsResponse, required: List with paginated items. The shape follows the IDENTIFIER used, not the caller: a numeric id returns the owner view (every field, requires ownership), a public identifier returns the published view (no connection paths, no contact details, no warmth) plus the screening rationale.
    - `id` number, nullable, required: Numeric list id — the handle for changing the list. Null when the list was read by its public identifier and you do not own it.
    - `public_id` string, nullable: Public identifier, e.g. "fintech-8f3k2". Present once the list has been published; it is what the public URL and a share prompt use. Null on a list that has never been published.
    - `is_public` boolean: Whether anyone holding the public identifier can read this list.
    - `viewer_can_manage` boolean: Whether the caller owns this list (or shares its workspace) and may therefore change it. Only sent on public-identifier reads, where ownership is not implied.
    - `title` string, required
    - `type` 'people' | 'company', required
    - `description` string, nullable, required
    - `item_count` number, required
    - `criteria` object[]: What the list was screened against. `id` is the short column label, `text` the full criterion. Only on public-identifier reads; pairs with each item's `screening.criteria_scores`.
      - `id` string, required
      - `text` string, required
    - `notifications_enabled` boolean
    - `results_diff_since_last_run` number, nullable
    - `created_at` string, required
    - `updated_at` string
    - `items` ListItem[], required
      - `id` number: Unique item identifier. Absent when the list was read by its public identifier — the id is a handle for mutating the row, and a public reader has nothing to mutate.
      - `graph_id` string, required: Graph database identifier
      - `type` 'people' | 'company', required: Entity type
      - `data` object, required: Entity data (profile information)
      - `screening` object, nullable, required: Autopilot screening result for this item, or null if the list has not been screened. Present so reading a screened list surfaces its scores. There is no stored pass/fail verdict — compare `score` against your own threshold.
        - `score` number, nullable, required: Autopilot overall_match_score (0–1), null if not yet scored
        - `match_brief` union: Short human-readable summary of WHY this item matched. Only on public-identifier reads.
          - string
          - object
            - `positive` string
            - `negative` string
          - unknown
        - `criteria_scores` object[]: Per-criterion scores, aligned with the list-level `criteria`. Only on public-identifier reads.
          - `criterion` string, required
          - `score` number, nullable, required
      - `created_at` string: ISO 8601 creation timestamp
  - `metadata` object, required
    - `request_id` string, required
  - `pagination` PaginationInfo, required: Cursor-based pagination metadata
    - `cursor` string, nullable, required: Opaque cursor for fetching the next page (null if no more results)
    - `has_next_page` boolean, required: Whether more results are available
    - `count` integer, required: Total number of results or count of items in current page

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - missing or invalid authentication
- `404`: List not found

---

[API](https://skmtc.dev/village/apis/village-v2-api.md) - [All operations](https://skmtc.dev/village/apis/village-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/village/apis/village-v2-api/revisions/aebe21a1a544?raw)