Pagination

1. No duplicate or skipped results — even if new records are added while you paginate
2. Consistent performance — does not degrade on large datasets

How it works#

Step 1 — Make your initial request (no searchAfter needed):

curl -X POST "https://api.ocean.io/v3/search/companies" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 100,
    "companiesFilters": {
      "primaryLocations": { "includeCountries": ["de"] }
    }
  }'

Step 2 — The response includes a searchAfter cursor and the total result count:

{
  "total": 48203,
  "searchAfter": "eyJzb3J0IjpbMC4wMDEsImFiYzEyMyJdfQ==",
  "companies": [ ... ]
}

Step 3 — Pass the cursor in your next request to get the next page:

curl -X POST "https://api.ocean.io/v3/search/companies" \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 100,
    "searchAfter": "eyJzb3J0IjpbMC4wMDEsImFiYzEyMyJdfQ==",
    "companiesFilters": {
      "primaryLocations": { "includeCountries": ["de"] }
    }
  }'

Step 4 — Repeat until searchAfter is absent or null in the response. That signals the last page.

Iterating all results in code#

import requests

def fetch_all_companies(filters, api_token, page_size=100):
    url = "https://api.ocean.io/v3/search/companies"
    headers = {"X-Api-Token": api_token, "Content-Type": "application/json"}
    results = []
    search_after = None

    while True:
        payload = {"size": page_size, "companiesFilters": filters}
        if search_after:
            payload["searchAfter"] = search_after

        response = requests.post(url, headers=headers, json=payload).json()
        results.extend(response["companies"])

        search_after = response.get("searchAfter")
        if not search_after:
            break

    return results

async function fetchAllCompanies(filters, apiToken, pageSize = 100) {
  const url = 'https://api.ocean.io/v3/search/companies';
  const headers = { 'X-Api-Token': apiToken, 'Content-Type': 'application/json' };
  const results = [];
  let searchAfter;

  do {
    const body = { size: pageSize, companiesFilters: filters };
    if (searchAfter) body.searchAfter = searchAfter;

    const data = await fetch(url, {
      method: 'POST',
      headers,
      body: JSON.stringify(body),
    }).then(r => r.json());

    results.push(...data.companies);
    searchAfter = data.searchAfter;
  } while (searchAfter);

  return results;
}

Page size limits#

Use the size parameter to control how many results are returned per page:

searchAfter and peoplePerCompany

The searchAfter parameter cannot be combined with the peoplePerCompany parameter in Search People. If you need peoplePerCompany, use the size parameter to cap your results instead. Note that size limits the maximum to 10,000 results in this mode.