> 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/check-list-status.md).

# Check List Status

Track the progress of your submitted list using this endpoint.

## Check List Status

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

{% hint style="info" %}
Checking list status is **free** — no credits are charged.
{% endhint %}

Track the progress of your submitted list.

**Headers**

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

**Body**

| Name       | Type   | Description                    |
| ---------- | ------ | ------------------------------ |
| `api_key`  | string | Your API Key.                  |
| `listname` | string | The name of the list to check. |

**Response**

The rows are under `data`, one per enrichment running on the list. See [Response Format](/getting-started/response-format.md) for the fields every endpoint returns.

| Field              | Description                                                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `list_name`        | The list being checked.                                                                                                                   |
| `status`           | Job state: `queued`, `processing`, `done`, `not_found`, `cancelled` or `error`.                                                           |
| `status_detail`    | Only present when a finished job has more to say about its result, for example `only contacts already in your lists`. Left out otherwise. |
| `enrichment_label` | Which enrichment this row is reporting on.                                                                                                |

`total` is the number of rows returned.

{% hint style="info" %}
Keep polling until `status` reads `done` — that is the finished state. `queued` and `processing` mean the job is still running.
{% endhint %}

**What each status means**

| `status`                                                           | Meaning                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `queued`                                                           | Waiting to start. Keep polling.                                                                                                                                                                                                                  |
| `processing`                                                       | Running. Keep polling.                                                                                                                                                                                                                           |
| `done`                                                             | Finished. Download the results.                                                                                                                                                                                                                  |
| `done` with `status_detail: "only contacts already in your lists"` | Finished, but everyone the search found was already in your account. Nothing new was added and the credits were refunded. This is not an error, and running the same search again gives the same result. Change your filters to find new people. |
| `not_found`                                                        | Finished, but the search found no one at all.                                                                                                                                                                                                    |
| `cancelled`                                                        | The job was stopped.                                                                                                                                                                                                                             |
| `error`                                                            | The job failed.                                                                                                                                                                                                                                  |

**Example**

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

```json
{
  "api_key": "your_api_key",
  "listname": "Sales Directors at Software Companies"
}
```

{% endtab %}

{% tab title="Output" %}

```json
{
  "status": "success",
  "data": [
    {
      "list_name": "Sales Directors at Software Companies",
      "status": "done",
      "enrichment_label": "Lead Enrichment"
    }
  ],
  "credits_used": 0,
  "total": 1,
  "success": true
}
```

{% endtab %}

{% tab title="Output (already in your lists)" %}

```json
{
  "status": "success",
  "data": [
    {
      "list_name": "Sales Directors at Software Companies",
      "status": "done",
      "status_detail": "only contacts already in your lists",
      "enrichment_label": "Lead Enrichment"
    }
  ],
  "credits_used": 0,
  "total": 1,
  "success": true
}
```

{% endtab %}

{% tab title="Error" %}

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

{% endtab %}
{% endtabs %}

Once your list reads `done`, download the results with Download List Data.