> 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/get-enrichment-results/download-list-data.md).

# Download List Data

Once the enrichment is complete, use this endpoint to retrieve your results.

## Download List Data

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

{% hint style="info" %}
Downloading list data is **free** - you've already paid for the enrichment.
{% endhint %}

**Headers**

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

**Body**

| Name                    | Type    | Description                                                                                                                         |
| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`               | string  | Your API Key                                                                                                                        |
| `listname`              | string  | The name of your list to download.                                                                                                  |
| `limit`                 | integer | Optional. Rows per page (minimum 1). Omit to download the full list.                                                                |
| `offset`                | integer | Optional. Rows to skip before the page starts (minimum 0, default 0). Use with `limit` to read a large list in pages.               |
| `include_empty_columns` | boolean | Optional, default `false`. Columns that are empty on every returned row are left out. Set `true` to get every column, empty or not. |

**Response**

The contact rows are under `data`, and `total` is how many rows are in this response. See [Response Format](/getting-started/response-format.md) for the fields every endpoint returns.

Wait until Check List Status reports `done` before downloading, so you get the whole list.

## Pages and empty columns

**Only filled-in columns come back.** A column is left out when it is empty on every row of the response, the same way the leads table hides it. A column with a value on any row is kept on every row, so all rows have the same keys. Empty means `null`, blank text, an empty list or an empty object. `false` and `0` are values and are kept. A missing column means no row in the response has a value for it. Send `include_empty_columns: true` to get every column.

**Read a large list in pages.** Send `limit` and `offset`. The first page is `offset: 0`, the next is `offset: 500`, then `1000`, and so on. Rows come back in the same order on every call, so pages do not overlap. A page with fewer rows than `limit` is the last one.

{% hint style="success" %}
A 5,000-row list can be read as ten pages of 500. Each page only carries the columns that page has values for.
{% endhint %}

**Example**

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

```json
{
  "api_key": "your_api_key",
  "listname": "Sales Directors at Software Companies",
  "limit": 500,
  "offset": 0
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "success",
  "data": [
    {
      "email": "alison.s@hubspot.com",
      "person_name": "Alison Savery",
      "organization_name": "HubSpot Ventures",
      "current_title": "inbound marketing manager",
      "person_linkedin_url": null,
      "current_company_website": "hubspot.com",
      "organisation_linkedin_url": "https://www.linkedin.com/company/68529",
      "current_industry": "internet",
      "address": "Cambridge, Massachusetts, US, 02141",
      "current_email_status": null,
      "city": "Cambridge",
      "state": "Massachusetts",
      "country": "US",
      "first_name": "Alison",
      "last_name": "Savery",
      "list_name": "Hubspot Employees",
      "log": null
    },
    {
      "email": "ashley.m@hubspot.com",
      "person_name": "Ashley Medina",
      "organization_name": "HubSpot",
      "current_title": "Security Manager",
      "person_linkedin_url": "http://www.linkedin.com/in/24infosec",
      "current_company_website": "hubspot.com",
      "organisation_linkedin_url": "http://www.linkedin.com/company/hubspot",
      "current_industry": "information technology & services",
      "address": "San Diego, California, United States",
      "current_email_status": "valid",
      "city": "San Diego",
      "state": "California",
      "country": "United States",
      "first_name": "Ashley",
      "last_name": "Medina",
      "list_name": "Hubspot Employees",
      "log": "Email Enrichment - Parvenu - Email Found (a.medina@hubspot.com) ✅ - 09-14-26 - 1 Credit - API"
    }
  ],
  "credits_used": 0,
  "total": 2,
  "success": true
}
```

{% endtab %}

{% tab title="Error" %}

```json
{
  "status": "error",
  "error": { "code": "not_found", "message": "Not Found" },
  "success": false
}
```

{% endtab %}
{% endtabs %}

{% hint style="success" %}
Your lists will also be available through the Parvenu dashboard.
{% endhint %}