---
title: "Refresh a list from its saved search"
method: POST
path: "/v2/lists/{id}/refresh"
tags: ["Lists"]
---

# Refresh a list from its saved search

`POST /v2/lists/{id}/refresh`

## Request

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

Re-run the saved search behind a list and append any new matches. Only lists created from a search can be refreshed — manual and imported lists have no query to re-run. The refresh runs in the background: poll get_list until the run completes. Existing items are never removed and email notification state is not affected. Refreshes are throttled per list; a 429 tells you how many seconds to wait. Pass `add` to top the list up by a specific number of people instead ("add more") — that variant also screens the new arrivals against the criteria already on the list, and is not throttled. The caller pays for the new rows with their credits: the run stops at what the balance covers, and a 402 means none are affordable.

## Path parameters

- `id` string, required: List ID

## Request body

- RefreshListRequest: Optional body for refreshing a list.
  - `add` integer: How many MORE items to add on top of what the list already holds ("add more"). Omit for a plain refresh, which tops the list up to the system limit. Supplying this also screens the newly-added items against the list's existing criteria, and bypasses the refresh cooldown — an explicit add is a deliberate, priced action rather than an accidental double-run.

## Response `200`

Refresh queued; poll the list until the run completes

- object
  - `data` RefreshListResponse, required: Response after queueing a list refresh. Poll get_list until the run completes (new items are appended; existing items are never removed).
    - `is_processing` boolean, required: True — the refresh was queued and is running in the background
  - `metadata` object, required
    - `request_id` string, required

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - missing or invalid authentication
- `402`: Not enough credits for a single new row (or no seat)
- `404`: List not found
- `409`: A refresh or import is already running on this list
- `422`: List is not backed by a saved search
- `429`: List was refreshed too recently

---

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