> For the complete documentation index, see [llms.txt](https://developer.parvenu.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.parvenu.io/search/funding-rounds/list-lookup.md).

# List Lookup

Save companies that just raised money into a Parvenu list, once or every day or week.

<mark style="color:green;">`POST`</mark> `/funding_search_list`

{% hint style="info" %}
Costs **1 credit per funding round saved**. Credits for up to `max_results` rounds, or for as many as your balance covers if that is fewer, are held when the job starts and the unused part is refunded when it finishes. If your balance covers fewer rounds than `max_results`, the run still goes ahead for as many rounds as your balance covers and `message` says so. Only a balance under 1 credit, too low for even one round, is refused with `402`, and then nothing runs.
{% endhint %}

Saves companies that recently announced a funding round into a list, one company row per company. It takes the same filters as [Individual Lookup](https://developer.parvenu.io/search/funding-rounds/individual-lookup.md), plus `listname` and `repeat`.

{% hint style="info" %}
This is a bulk endpoint. The process has three steps: (1) start the job here, (2) check status with `/check_list_status`, (3) download results with `/download_list`.
{% endhint %}

{% hint style="warning" %}
**Companies only.** Each row is a company with no person on it. To find people there, once the run is done, read the domains with [Download List](https://developer.parvenu.io/get-enrichment-results/download-list-data.md) and call [Lead Enrichment (List)](https://developer.parvenu.io/search/lead-enrichment.md) with them in `company_domain` and the same `listname`.
{% endhint %}

### Each list gets a round only once

* The **first** run into a list looks back as far as `lookback` (`today`, `7d` or `30d`).
* **Later** runs into the same list bring only rounds that list has not had yet, plus any an earlier run's `max_results` left out (never more than 30 days back).
* A company that raises again keeps its one row. The new round is added to `funding_rounds` and the `latest_funding_*` columns are updated.

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Body**

| Name                                                                                                                       | Type    | Description                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`                                                                                                                  | string  | **Required.** Your API key.                                                                                                              |
| `listname`                                                                                                                 | string  | **Required.** The list to save the companies into. Created if it does not exist.                                                         |
| `stages`, `include_other_rounds`, `sectors`, `country`, `state`, `min_amount_usd`, `max_amount_usd`, `investor`, `keyword` |         | Optional. The same filters as [Individual Lookup](https://developer.parvenu.io/search/funding-rounds/individual-lookup.md).              |
| `lookback`                                                                                                                 | string  | Optional. How far back the **first** run looks: `today`, `7d` (default) or `30d`. Later runs bring only rounds the list has not had yet. |
| `max_results`                                                                                                              | integer | Optional. Most rounds to save in one run, 1 to 1,000. Default 25.                                                                        |
| `repeat`                                                                                                                   | string  | Optional. `once` (default), `daily` or `weekly`. `daily` or `weekly` saves the search and runs it again into the same list.              |

### Repeating a list

With `repeat` set to `daily` or `weekly`, the search is saved and runs again into the same list on that timetable. Each run brings only new rounds and is billed the same way as the first. See every repeating list with [List Schedules](https://developer.parvenu.io/search/funding-rounds/list-schedules.md), and stop one with [Stop a Schedule](https://developer.parvenu.io/search/funding-rounds/stop-a-schedule.md).

{% hint style="info" %}
In a Flow, leave `repeat` alone and use the flow's own Schedule trigger instead.
{% endhint %}

### Columns written

| Column                      | Description                                                 |
| --------------------------- | ----------------------------------------------------------- |
| `funding_rounds`            | Every round the list has for this company, as a JSON array. |
| `latest_funding_stage`      | The newest round's type in plain words, e.g. `"Series A"`.  |
| `latest_funding_amount_usd` | The newest round's amount in US dollars.                    |
| `latest_funding_date`       | The newest round's date.                                    |
| `latest_funding_investors`  | The newest round's investors.                               |

The company columns are filled in too: name, website, LinkedIn, industry, location, description and logo.

**Response**

This endpoint starts a background job and answers with an acknowledgement, not the companies. See [Response Format](https://developer.parvenu.io/getting-started/response-format.md) for the fields every endpoint returns.

| Field                                           | Description                                                                                                              |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `status`                                        | `queued` once the job is accepted.                                                                                       |
| `job_id`                                        | The job handle.                                                                                                          |
| `list_name`                                     | The list the companies are being saved into.                                                                             |
| `rows_selected`                                 | How many rounds the job will look for.                                                                                   |
| `max_rows`                                      | How many you asked for.                                                                                                  |
| `credits_estimated`                             | What this run can spend: credits for up to `max_results` rounds, or for as many as your balance covers if that is fewer. |
| `credits_used`                                  | Credits taken so far.                                                                                                    |
| `credits_per_row`                               | Credits per round saved (`1`).                                                                                           |
| `credits_held`, `units_held`, `units_requested` | Present when credits are held: what was held and for how many rounds. The unused part comes back when the run finishes.  |
| `repeat`                                        | `once`, `daily` or `weekly`.                                                                                             |
| `next_run_at`                                   | When a repeating list runs next. `null` for `once`.                                                                      |
| `message`                                       | A short note about the job.                                                                                              |

**Example**

{% tabs %}
{% tab title="Input" %}

```json
{
  "api_key": "your_api_key",
  "listname": "Series A in Georgia",
  "stages": ["seed", "series_a"],
  "state": "GA",
  "lookback": "30d",
  "max_results": 25,
  "repeat": "weekly"
}
```

{% endtab %}

{% tab title="Output" %}
An example of the response shape.

```json
{
  "status": "queued",
  "job_id": "3f9c2a7e5b1d4c8a9e6f0b2d7a4c1e58",
  "list_name": "Series A in Georgia",
  "view": "all",
  "rows_selected": 25,
  "max_rows": 25,
  "truncated": false,
  "credits_estimated": 25.0,
  "credits_used": 25.0,
  "credits_per_row": 1.0,
  "credits_held": 25.0,
  "units_held": 25,
  "units_requested": 25,
  "repeat": "weekly",
  "next_run_at": "2026-10-30T19:00:00Z",
  "message": "Funding Rounds queued for up to 25 rounds. 25 credits held; unused credits are refunded when the run finishes.",
  "success": true
}
```

{% endtab %}
{% endtabs %}

**Retrieving results**

* [Check List Status](https://developer.parvenu.io/get-enrichment-results/check-list-status.md)
* [Download List Data](https://developer.parvenu.io/get-enrichment-results/download-list-data.md)
