How to Export 50,000 Leads to CSV (Python)

You export 50,000 leads from Python with one POST /v1/exports, a polling loop and a streamed download. The server walks the list, so you never page through results yourself.

TL;DR

• The whole script is 42 lines of Python 3 and the requests package.
• Setup takes about 10 minutes. The export runs in the background and tells you how long to wait between polls (pollAfter).
• It writes up to 50,000 rows. Each row counts 1 record, or 2 when the columns need an enrichment, as the full preset does (perRow in the 202 response says which).
• Bulk CSV export is not on Free. On Solo ($97 a month) a 50,000-row export with contact columns passes the pace of 10k enrichments every 5 hours and slows down. Agency ($497 a month) fits this size.

Prerequisites

• Python 3.9 or later and pip install requests.
• A LeadOcean API key on a paid plan, exported as $LEADOCEAN_API_KEY. Create an account at app.leadocean.io.
• A filter set. Size it first with the free count call so you know the export will fill.

Step 1: Size the list for free

Counting spends no records. Run it before you reserve 50,000.

curl -s "https://api.leadocean.io/v1/people/search?count=true&limit=1" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"jobLevel":["VP"],"jobFunction":["Sales & Business Development"],"country":["US"]}'

meta.total is capped at 100,000. The MCP tool leadocean_count_leads does the same job. Enum values are exact strings, so check them with GET /v1/enums before you guess.

Step 2: Create the export with retries on 429

A 429 means you sent requests faster than your plan allows: 5 a second on Free, 50 on Solo, 200 on Agency. The response carries Retry-After. The helper honors it and gives up after 5 tries.

Create export.py:

import os, sys, time, requests

http = requests.Session()
http.headers["x-api-key"] = os.environ["LEADOCEAN_API_KEY"]
BASE = "https://api.leadocean.io"

def call(method, path, **kw):
    for attempt in range(6):
        r = http.request(method, BASE + path, **kw)
        if r.status_code != 429 or attempt == 5:
            return r
        time.sleep(float(r.headers.get("Retry-After", 2 ** attempt)))

body = {
    "name": "vp-sales-us",
    "filters": {
        "jobLevel": ["VP"],
        "jobFunction": ["Sales & Business Development"],
        "country": ["US"],
    },
    "limit": 50000,
    "preset": "full",
}
r = call("POST", "/v1/exports", json=body)
if not r.ok:
    sys.exit(f"{r.status_code} {r.text}")
exp = r.json()["data"]

The filters object takes any people-search filter except cursor, limit, count and facets. The full preset has 45 columns and needs the enrich scope. The search preset has 27 columns and no contact points. perRow in the 202 response says what each row counts: 1, or 2 when the columns need an enrichment.

Step 3: Poll until the job is done

The create call answers 202 with the export object. Wait pollAfter seconds, then GET /v1/exports/{id} until status leaves queued and running. One export runs per account at a time, so a second job waits in the queue.

Append to export.py:

while exp["status"] in ("queued", "running"):
    time.sleep(exp.get("pollAfter") or 5)
    r = call("GET", f"/v1/exports/{exp['id']}")
    r.raise_for_status()
    exp = r.json()["data"]
    print(exp["status"], exp["rows"], "rows")

Step 4: Stream the file to disk

When status is done, download the CSV. The file stays available for 7 days. A 409 means the job is still running and a 410 means the file expired.

Append to export.py:

if exp["status"] != "done":
    sys.exit(f"Export ended as {exp['status']}: {exp.get('error')}")

with call("GET", f"/v1/exports/{exp['id']}/download", stream=True) as r:
    r.raise_for_status()
    with open("leads.csv", "wb") as f:
        for chunk in r.iter_content(1 << 16):
            f.write(chunk)
print("Saved leads.csv")

Run it with python export.py. Rows are deduplicated by person_id, so the file can hold fewer rows than you asked for. You are billed for rows written, and the unused reservation comes back.

What you get

A free count for the Step 1 filters on 2026-10-21, from leadocean_count_leads:

{ "total": 129494, "totalIsExact": true, "totalAll": 350517, "distinctCompanies": 58121 }

total counts people with a verified, catch-all-valid or catch-all email (the tool's default). totalAll is the same filters with no email condition. Either figure is above 50,000, so the export fills.

The export object, response shape from the API reference, placeholder values:

{
  "success": true,
  "data": {
    "id": "exp_acme123",
    "name": "vp-sales-us",
    "status": "queued",
    "requested": 50000,
    "rows": 0,
    "billed": 0,
    "pollAfter": 5
  }
}

The CSV headers for numbered blocks come back as email_1_address, email_2_address and phone_1_number.

Troubleshooting

FAQ