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

Start the export with POST /v1/exports, poll it until it is done, then stream the CSV from downloadUrl. The whole job is one script that uses only the Ruby standard library.

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 with the search preset, one per row written. Bulk CSV export is not on Free, so you need Solo ($97 a month) or Agency ($497 a month).

Prerequisites

• Ruby 3.0 or newer. No gems: the script uses net/http, json and uri.
• 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 writes the file. Save it as export.rb.

require "net/http"
require "json"
require "uri"

BASE = "https://api.leadocean.io"

def call(method, path, body = nil)
  6.times do |try|
    uri = URI(path.start_with?("http") ? path : BASE + path)
    req = Net::HTTP.const_get(method.capitalize).new(uri)
    req["x-api-key"] = ENV.fetch("LEADOCEAN_API_KEY")
    req["content-type"] = "application/json"
    req.body = body.to_json if body
    res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
    return res unless res.code == "429"
    sleep [res["Retry-After"].to_i, 2**try].max
  end
  raise "still 429 after 6 tries"
end

res = call("post", "/v1/exports", {
  name: "directors-us", limit: 50_000, preset: "search",
  filters: { jobLevel: ["Director"], country: ["US"] }
})
abort "#{res.code} #{res.body}" unless res.code == "202"
id = JSON.parse(res.body)["data"]["id"]

loop do
  s = JSON.parse(call("get", "/v1/exports/#{id}").body)["data"]
  puts "#{s["status"]} #{s["rows"]} rows"
  abort "export #{s["status"]}" if %w[failed cancelled].include?(s["status"])
  if s["status"] == "done"
    File.open("leads.csv", "wb") do |f|
      uri = URI(s["downloadUrl"])
      Net::HTTP.start(uri.host, uri.port, use_ssl: true) do |h|
        h.request_get(uri) { |r| r.read_body { |chunk| f.write(chunk) } }
      end
    end
    break
  end
  sleep [s["pollAfter"].to_i, 5].max
end

The retry reads Retry-After first and falls back to 1, 2, 4 seconds and so on. The download link is signed and opens without a key, so the script fetches it without the x-api-key header. The read_body block writes the file in chunks, so a 50,000-row CSV never sits in memory.

Step 3: Run it

export LEADOCEAN_API_KEY=your_key_here
ruby export.rb

The loop prints the status and the rows written so far. When the status is done, the CSV is in leads.csv.

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 and add caps.

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

perRow in the 202 response says what each row counts: 1, or 2 when the columns need an enrichment, as full does. Enriched rows also count against the enrichment pace (10k every 5 hours on Solo, 1M a day on Agency).

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. It counts verified and catch-all emails only, which is its default filter and not a mailable guarantee. One export takes the first 50,000.

Troubleshooting

FAQ