What is a bulk export? Bulk export vs paged search

A bulk export writes a whole filtered list to one CSV file, while paged search returns the same people 100 at a time. Use search to look and export to take.

Key takeaways

• A bulk export is a people search that writes rows to a file. It takes the same filters as search.
• Paged search returns up to 100 rows per call and you follow a cursor. An export writes up to 50,000 rows per request.
• On LeadOcean both cost 1 record per row, so the choice is about delivery, not price.
• Count first. The count is free, and it tells you which of the two you need.

What it is

A bulk export is a background job that runs a filtered people search and writes every matching row to a single CSV file you download.

The request is short. You send filters, a row limit and a column preset. The server admits the job or refuses it on the spot, then builds the file in a worker. You poll for the result, or wait for the email.

Think of it as the difference between reading a report on screen and printing it. Both show the same data. One is built for a quick look and the other for handing over.

Paged search is the opposite shape. You send the filters, you get one page back, and you ask again for the next page. Your code stays in the loop for the whole list.

How it works

An export is five steps. You touch the first two. The server does the rest.

1. Count the list. Send a search with count=true and limit 1. It costs nothing and returns the total in meta.total.
2. Start the export. POST /v1/exports with a filters object, a limit and a preset. The API answers 202 with a job id.
3. The server reserves records. One per row requested. Records for rows never written are released.
4. A worker writes the file. It dedupes on person_id and builds a plain .csv, never a zip.
5. You download it. Poll GET /v1/exports/{id}, then fetch GET /v1/exports/{id}/download. Files are kept for 7 days.

Here is a worked example with a made-up size. Suppose a count says your filter matches 12,000 people.

With paged search at limit 100, that is 120 calls, each carrying a cursor from the last. You write the loop, handle a failed page and append rows to a file yourself.

With an export, it is one request, one poll loop and one file of 12,000 rows. The same 12,000 records are spent either way.

Bulk export vs paged search

Paged search is for looking. A bulk export is for taking the list away. The table shows the practical differences on LeadOcean.

Read the table by job, not by feature. If a human or an agent will look at the rows, you want JSON and small pages. If a program or a teammate will use the rows, you want the file.

The two share filters on purpose. Anything you can find with search you can export, so a count you ran once stays valid for both.

When it matters

The difference shows up the moment the list is bigger than one screen.

You are loading a list into another tool

Choose the export. It is the shape these tools already expect. A CRM import, a sequencer upload or a spreadsheet wants a file. Building one from 500 pages of JSON is work you do not need to do.

You are checking a filter before you commit

Choose paged search. Pull 25 rows with limit 25 and read the titles and companies. If the shape is wrong, you spent 25 records and changed a filter. The free plan has 1,000 records one-off, so this is a good use of them. An AI agent works the same way: the MCP server has search_leads for the sample and export_leads for the file. Both charge 1 record per row, and count_leads is free.

Your list is over 50,000 rows

Run several exports with filters that do not overlap, such as one per employeeRange or country, so no row is bought twice. An account can export 500,000 rows a day. The 1M-record walkthrough has the full loop.

You need the list to be repeatable

Choose the export and keep its name. A named job has an id, a row count and a file you can download again for 7 days. A paged loop leaves only the rows your own code saved. If a teammate asks what you pulled, the export is the record.

How LeadOcean handles it

Search and export take the same filters, so you size once and then pick the shape. The first call below sizes the list and is free: count=true goes in the URL, not the body, and limit stays 1. The second call exports it and spends 1 record per row written. meta.total stops at 100,000 on the API.

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

curl -X POST "https://api.leadocean.io/v1/exports" \
  -H "x-api-key: $LEADOCEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "us-sales-vps",
    "filters": {
      "jobLevel": ["VP"],
      "jobFunction": ["Sales & Business Development"],
      "country": ["US"],
      "emailStatus": ["verified", "catch_all_valid", "catch_all"]
    },
    "limit": 5000,
    "preset": "full"
  }'

Pass emailStatus in both calls so the count and the file use the same definition of mailable. The search preset is 27 columns with no contact points. The full preset is 45 columns with emails 1 to 3 and phones 1 to 2, and it needs the enrich scope.

You can also run it without code. The Exports page in the app at app.leadocean.io has a filter builder, a column picker with presets, the record price before you start and a CSV download. Details are on the bulk export product page and the bulk CSV export guide.

A failed or cancelled export releases the records it reserved for rows it never wrote. Check billed and rows on the finished job before you move on.

Pro is $499 a month, flat. Free is 1,000 records, one-off, no card. See pricing.

FAQ