Lists

Refresh a list from its saved search

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.

post/v2/lists/{id}/refresh

Request

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

Path parameters

idstring required

List ID

Example:123

Request body

addinteger

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.

Example request

{
  "add": 500
}

Response

Refresh queued; poll the list until the run completes

Changes

No recorded changes to this operation across all 1 revision of this API.