---
title: "Get all lists"
method: GET
path: "/v2/lists"
tags: ["Lists"]
---

# Get all lists

`GET /v2/lists`

## Request

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

Get all your saved lists. Use this to see your collections of people or companies. Supports pagination (page, limit), filtering by type (people or company), and searching by title. Each list includes: id, title, type, description, item_count, and timestamps. Set include_summary=true to also get each list’s screening status, criteria and match counts, a preview of its members, and its import state.

## Query parameters

- `cursor` string: Opaque cursor for pagination (from previous response)
- `limit` string: Number of lists per page (max 100)
- `type` 'people' | 'company': Filter lists by type
- `search` string: Search lists by title
- `include_summary` 'true' | 'false': Add a `summary` object to each list: screening status, criteria and counts, a preview of the most recent members, and import state. Off by default; the default response is unchanged.

## Response `200`

Lists retrieved successfully

- object
  - `data` ListsListItem[], required: Response containing paginated list of user lists
    - `id` number, required: Unique list identifier
    - `title` string, required: List title
    - `type` 'people' | 'company', required: Type of entities in the list
    - `description` string, nullable, required: List description
    - `item_count` number, required: Number of items in the list
    - `notifications_enabled` boolean, required: Whether the list is opted into the daily "new search results" email sweep
    - `is_public` boolean, required: Whether anyone holding the public identifier can read this list.
    - `public_id` string, nullable, required: Public identifier, minted the first time the list is published. Null until then.
    - `results_diff_since_last_run` number, nullable, required: New items appended by the most recent completed fill run (creation fill, manual refresh, or nightly re-run). Null until a run records one.
    - `created_at` string, required: ISO 8601 creation timestamp
    - `updated_at` string, required: ISO 8601 last update timestamp
    - `summary` ListSummary: Present only when the request sets `include_summary=true`.
      - `screening_status` 'na' | 'pending' | 'success' | 'fail' | 'outdated', required: `na` never screened, `pending` screening in progress, `success` screened, `fail` screening failed, `outdated` criteria changed since the last run.
      - `screening_criteria` object[], required: What the list is screened against. `id` is the short label, `text` the full criterion. Empty when the list has no criteria.
        - `id` string, required
        - `text` string, required
      - `screened_count` number, nullable, required: Items screened so far. Null unless screening is in progress or finished (`pending` or `success`).
      - `strong_match_count` number, nullable, required: Screened items scoring 50% or higher against the criteria. Null whenever `screened_count` is null.
      - `member_preview` object[], required: Up to 12 of the most recently added members, newest first, for a facepile.
        - `name` string, required
        - `avatar` string, nullable, required
        - `linkedin_identifier` string, nullable, required
      - `imported` boolean, required: Whether the list was built from an import.
      - `import_status` 'pending' | 'processing' | 'completed' | 'failed' | 'confirmed', nullable, required: State of the import that built the list. An imported list is ready to browse once `confirmed`. Null on a list that was not imported.
      - `import_in_progress` boolean, required: Whether an import is running on the list right now: a file being added to it, or its members being imported as relationships. Unlike `import_status`, this covers imports into a list that already existed.
      - `recent_search` boolean, required: Whether the row is a legacy "recent search" record rather than a list the user saved. Browsing surfaces hide these.
      - `last_run_completed_at` string, nullable, required: ISO 8601 time the most recent fill run finished. Null while the first run is still filling the list.
  - `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

---

[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)