> 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/enrichments/company-news/list-lookup.md).

# List Lookup

Find recent news for every company in a Parvenu list. Asynchronous, writes results back into the list.

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

{% hint style="info" %}
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 company that returns news**, the same rate a single [Individual Lookup](/enrichments/company-news/individual-lookup.md) costs. Each company is charged once, however many of its contacts are on the list. Companies that find nothing are free. Results are written to the `company_news` column.
{% endhint %}

Use this to find news for every company on a list in one call, rather than looping over [Individual Lookup](/enrichments/company-news/individual-lookup.md) per row.

**Charged once per company.** Contacts at the same company (the same website domain) share one answer. The company is looked up and charged once, and the other contacts at that company get the same news for 0 credits, with `(same company)` in their `log`.

**There is no `prompt` field.** Company News asks a fixed question, so every list is asked the same thing and the answers stay comparable across runs. Sending a `prompt` returns a 422. To run a question of your own wording across a list, use [Research with AI](/enrichments/research-with-ai.md) instead.

**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.                                                                                                                                |
| `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](/manage-lists/list-saved-views.md).

**Processing modes**

| Value        | Behaviour                                                                                                       |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| `blank_only` | Default. Only fills rows whose `company_news` column is still empty. Cheapest re-run.                           |
| `all`        | Re-processes every row and replaces what is there. A row that finds nothing on the re-run has its cell cleared. |
| `first_10`   | Processes only the first 10 fetched rows. Use this as a cheap dry run.                                          |

**View values**

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

**Example**

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

```json
{
  "api_key": "your_api_key",
  "listname": "my_list",
  "processing_mode": "first_10"
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "success": true,
  "job_id": "a1b2c3d4e5f6",
  "status": "queued",
  "list_name": "my_list",
  "rows_selected": 10,
  "rows_fetched": 10,
  "message": "News lookup started in background.",
  "view": "all",
  "max_rows": 5000,
  "credits_estimated": 10,
  "truncated": false,
  "credits_used": 0
}
```

{% endtab %}

{% tab title="Error" %}

```json
{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "prompt: Extra inputs are not permitted"
  },
  "success": false
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`credits_estimated` is `rows_fetched` × 1, the most the run can cost. The final spend is usually lower: contacts at the same company share one charge, and two cases are free (a company with no recent news, and a row with no company website to search on). `credits_used` on the acknowledgement is 0 because nothing has run yet. `job_id` identifies this run and also appears in each processed row's `log` entry.
{% endhint %}

{% hint style="info" %}
Try a new list with `"processing_mode": "first_10"` first. At `all` a re-run replaces results you already have.
{% endhint %}

**Retrieving results**

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