List Lookup

Run a web-search-backed research prompt against every row of a Parvenu list. Asynchronous, writes results back into the list.

POST /research_with_ai_list

Your prompt must reference at least one column using {{column_name}} syntax. A prompt with no column reference is rejected with a 400, see Prompt requirements below.

This is an asynchronous endpoint. It returns a job acknowledgement, not data. Poll /check_list_status until the list reports done, then fetch the rows with /download_list. Costs 1 credit per row, charged only when the model returns text. Results are written to the research_with_ai column.

Use this to run a prompt against every row of a list in one call, rather than looping over Individual Lookup per row.

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description
api_key	string	Your API Key.
listname	string	Name of the existing Parvenu list to enrich.
prompt	string	The prompt to run against each row. Must contain at least one {{column_name}} reference.
processing_mode	string	Optional. blank_only (default), all, or first_10. See Processing modes below.
view	string	Optional. Which rows of the list to process. all (default) processes every contact in the list; verified restricts the run to contacts whose email address is verified.
saved_view	string	Optional. Name of a saved view on this list. Runs only on the contacts in that view. Don't combine with view, filter_stack or search.

Saved views. To run only on the contacts in a saved view, send its name as saved_view. See List Saved Views.

Prompt requirements

The prompt is a template, not a standalone question. Reference list columns with double curly braces and the API substitutes each row's value before sending it to the model:

In one sentence, what does {{organization_name}} do?

If your prompt contains no column reference at all, the call fails with a 400 and the message No column references found in prompt. Use {{column_name}} format.

Which columns can I reference? Any column on the list: the exact set is the keys returned by Download List Data for that list.

Processing modes

Value	Behaviour
blank_only	Default. Only fills rows whose target column is still empty. Cheapest re-run.
all	Re-processes and overwrites every row.
first_10	Processes only the first 10 fetched rows. Use this to test a prompt cheaply.

View values

Value	Processes
all	Every row in the list (default).
verified	Only rows whose email address is verified.

Example

Input

{
  "api_key": "your_api_key",
  "listname": "my_list",
  "prompt": "What is {{organization_name}}'s most recent public funding round or acquisition, if any?",
  "processing_mode": "first_10"
}

Output

{
  "success": true,
  "job_id": "210",
  "status": "queued",
  "list_name": "my_list",
  "rows_selected": 10,
  "rows_fetched": 10,
  "message": "Research processing started in background. Only first 10 fetched records will be processed; existing results will be replaced.",
  "view": "all",
  "max_rows": 5000,
  "truncated": false,
  "credits_used": 0
}

Error

{
  "status": "error",
  "error": {
    "code": "http_error",
    "message": "Failed to start AI research due to external API error",
    "detail": "External API error: 400 - No column references found in prompt. Use {{column_name}} format."
  },
  "success": false
}

Reading the acknowledgement

Every list-scoped trigger answers with the same envelope, so one piece of client code handles them all.

Field	Meaning
job_id	Identifier for this run. Always a string. For AI triggers it is the id of the saved prompt.
status	A job status: queued, processing, done, not_found, cancelled or error.
rows_selected	How many rows matched your view before the page limit was applied.
rows_fetched	How many rows this run actually picked up. This is the number that gets processed.
max_rows	The ceiling a single run will fetch.
truncated	true when the list was longer than max_rows and the run was cut to fit.

Test new prompts with "processing_mode": "first_10" before running them across a full list. The prompt is saved and reused on later runs (job_id is that saved prompt's id), so a bad prompt run at all will overwrite good results.

Retrieving results

• Check List Status

• Download List Data