Check List Status

Track the progress of your submitted list using this endpoint.

Check List Status

POST /check_list_status

Checking list status is free — no credits are charged.

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 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.

Keep polling until status reads done — that is the finished state. queued and processing mean the job is still running.

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.

Lead search credits

A lead search holds credits for every row you ask for when it starts, then gives back what it did not use once it finishes, usually within a minute or two. When the list has a finished lead search, the response also includes lead_search_credits for the newest one. The key is left out otherwise.

Field	Description
credits_held	Credits taken when the search started.
credits_used	Credits the search kept.
credits_refunded	Credits given back.
refund_reason	One plain sentence saying why, for example All 3 people found were already in your account, so they were free.
finished_at	When the search ended (ISO 8601).

Example

Input

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

Output

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

Output (already in your lists)

{
  "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
}

Output (lead search credits)

{
  "status": "success",
  "data": [
    {
      "list_name": "Sales Directors at Software Companies",
      "status": "done",
      "status_detail": "only contacts already in your lists"
    }
  ],
  "credits_used": 0,
  "total": 1,
  "success": true,
  "lead_search_credits": {
    "credits_held": 0.6,
    "credits_used": 0.0,
    "credits_refunded": 0.6,
    "refund_reason": "All 3 people found were already in your account, so they were free.",
    "finished_at": "2026-10-12T23:07:52.84805+00:00"
  }
}

Error

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

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