How to export 50,000 leads to CSV (in TypeScript)

Start the export with POST /v1/exports, poll it until the status is done, then stream the CSV from downloadUrl. The whole job is one file that uses Node's built-in fetch, so there is nothing to install except a TypeScript runner.

TL;DR

• One export is up to 50,000 rows. The account ceiling is 500,000 rows a day.
• It takes about 15 minutes to set up. The export runs on a worker, so you poll while it builds.
• It spends up to 50,000 records, one per row written. Bulk CSV export is not on Free, so you need Solo ($97 a month) or Agency ($497 a month).

Prerequisites

• Node 20 or newer (built-in fetch) and npx tsx to run TypeScript without a build step.
• A LeadOcean key on a paid plan, exported as $LEADOCEAN_API_KEY. Get one at app.leadocean.io.
• A filter set. Size it first with the free count call so you know the list is at least as big as you ask for.

Step 1: Size the list for free

Counting costs nothing, so do it before you reserve 50,000 records. The free leadocean_count_leads MCP tool and count=true on search take the same filters as the export.

curl -s "https://api.leadocean.io/v1/people/search?count=true" \
  -H "x-api-key: $LEADOCEAN_API_KEY" -H "content-type: application/json" \
  -d '{"jobLevel":["Director"],"country":["US"],"limit":1}'

Filters are arrays of strings and enum values are exact: Director, not director, and US, not United States.

Step 2: Write the export client

This script creates the export, retries on 429, polls until the status is done, and streams the file to disk. Save it as export.ts.

import { createWriteStream } from "node:fs";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";

const BASE = "https://api.leadocean.io";
const sleep = (s: number) => new Promise((r) => setTimeout(r, s * 1000));

async function call(method: string, path: string, body?: unknown) {
  for (let attempt = 0; attempt < 6; attempt++) {
    const res = await fetch(BASE + path, {
      method,
      headers: {
        "x-api-key": process.env.LEADOCEAN_API_KEY!,
        "content-type": "application/json",
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    if (res.status !== 429) return res;
    const text = await res.text();
    if (text.includes("export_limit")) throw new Error(text); // daily ceiling, not a rate limit
    await sleep(Number(res.headers.get("retry-after")) || 2 ** attempt);
  }
  throw new Error("still 429 after 6 tries");
}

const created = await call("POST", "/v1/exports", {
  name: "directors-us",
  limit: 50000,
  preset: "search",
  filters: { jobLevel: ["Director"], country: ["US"] },
});
if (created.status !== 202) throw new Error(`${created.status} ${await created.text()}`);
const { id } = (await created.json()).data;

while (true) {
  const { data } = await (await call("GET", `/v1/exports/${id}`)).json();
  console.log(data.status, data.rows, "rows");
  if (data.status === "failed" || data.status === "cancelled") {
    throw new Error(`export ${data.status}: ${data.error?.message ?? ""}`);
  }
  if (data.status === "done") {
    const file = await fetch(data.downloadUrl);
    await pipeline(Readable.fromWeb(file.body as any), createWriteStream("leads.csv"));
    break;
  }
  await sleep(data.pollAfter ?? 5);
}

The retry reads Retry-After first and falls back to 1, 2, 4 seconds and so on. A 429 that names export_limit is the daily ceiling, so the script stops instead of retrying. The download link is signed and opens without a key, so the final fetch sends no header.

Step 3: Run it

export LEADOCEAN_API_KEY=your_key_here
npx tsx export.ts

The loop prints the status and the rows written so far. When the status is done, the CSV is in leads.csv. There is no cursor to walk: the worker pages the index for you, and pollAfter tells you how long to wait between checks.

Step 4: Add contact columns when you need them

The search preset has 27 columns and no contact points. The default full preset has 45 columns, including emails 1 to 3 and phones 1 to 2, and it needs the enrich scope. Swap the preset in the body:

{"name":"directors-us-full","limit":50000,"preset":"full",
 "filters":{"jobLevel":["Director"],"country":["US"]},
 "caps":{"emails":2,"phones":1}}

Every row costs one record whatever the columns. With the full preset the export reserves up to two records a row while it runs, so check your remaining records first.

What you get

The call to POST /v1/exports returns 202 with the export. This is the response shape from the API reference, with placeholder values:

{
  "success": true,
  "data": {
    "id": "exp_acme_0001",
    "name": "directors-us",
    "status": "queued",
    "requested": 50000,
    "estimatedTotal": 4798296,
    "rows": 0,
    "billed": 0,
    "pollAfter": 5
  }
}

On 2026-10-21 the free leadocean_count_leads tool returned 4,798,296 people for jobLevel Director in country US. That is its default: people whose best email is verified, catch_all_valid or catch_all. With no email condition the same filters match 12,741,708 people. One export takes the first 50,000.

Troubleshooting

FAQ