Pre-Black Friday: 20% off, for as long as you stayEARLYBFon Solo and AgencyEnds Nov 28Start free

Documentation

Records, limits and errors

Usage is metered in records returned — not in requests, not in credits with a multiplier. Here is exactly what a call costs, how fast you may call, and what every failure means.

How records are counted

Every person or company we hand back counts one record. Nothing carries a surcharge: revealing a person's email addresses and phone numbers costs the same as not revealing them.

Sizing a search is free. Send count=true with limit=1 to either search endpoint and you get the total in meta.total, an empty data and meta.countOnly: true — no records spent, however often you ask. That is the call to make before you buy a segment; agents get the same thing from the leadocean_count_leads tool. For companies there is a dedicated door: GET /v1/companies/count (tool leadocean_count_companies) takes the company-search filters and answers the exact total with breakdowns by industry, headcount band, HQ country, HQ state and NAICS — free, no rows. A people count also carries meta.distinctCompanies, how many employers the matched people span. A count=true with any larger limit is an ordinary page you pay for, with the total attached.

CallCostsNotes
A search page of 2525 recordsOne per person or company handed back. Ask for fewer and you are charged for fewer.
Enriching one person1 recordThe same whether or not you reveal emails and phone numbers.
One company lookup1 recordThe same whether you came in by domain or LinkedIn URL.
A 404 — nobody matchednothingYou are only charged for records you actually receive.
A 429, a 402 or a 503nothingRejected requests are never metered.
GET /v1/filters, /v1/enums, /v1/usage, /v1/accountnothingReference and account endpoints are free.
GET /v1/companies/countnothingSizing with breakdowns is free, however often you ask.

The free 1,000 are a one-off. They are an allowance to try the API with, not a monthly grant, and they never reset. A paid plan has no monthly figure to come back: it has a fair-use pace, so many records per window, and reaching it slows you down rather than stopping you. Free and Solo get one key, Agency five, Platform twenty — see pricing.

Rate limits

Speed is what the plans price: 5 requests a second on Free, 50 on Solo, 200 on Agency and 10,000 on Platform, per account (all its keys and team members share it), paced evenly rather than allowed in one burst at the top of each second. Over that you get 429 with Retry-After: 1, and X-RateLimit-Limit names the rate in force. The limit is per account: every key and every team member on the account shares it, so splitting a job across several keys or people does not make it faster. GET /v1/account reports your rate.

limit goes up to 100 records per search request, so 50 requests a second is a much larger number of records a second than it sounds — ask for full pages rather than making more calls.

How deep one search can page

Paging through a single search stops after a fixed number of rows — 10,000 by default. The page that reaches the cap carries meta.depthCapped: true and no meta.nextCursor, so a loop that pages until the cursor runs out already stops in the right place. Past that point, narrow the filters and run a tighter search rather than walking the whole index.

It applies to people search, to company search, and to the company contact list at GET /v1/companies/{domain}/people. The contact list was uncapped until today — an integration that pages past 10,000 people at one company will now stop there instead of continuing.

Rows paged through, not records bought. Two different numbers, and easy to confuse. The depth cap is how far one query may walk. Your records are what you may buy in total, across every query, for the month. Ten searches of 10,000 rows each is 100,000 records and never touches the cap; one search walked to 10,001 rows hits the cap whatever your allowance still has in it.

The cap is per account, and it can be raised or lowered. If you have a workload that genuinely needs to page deeper, email support@leadocean.io and say what you are paging and why.

The fair-use pace, and what happens when you reach it

Nothing stops. Solo, Agency and Platform have no bucket of records to run out of. Each has a pace: so many records received per window, counted separately for search (people and company search pages) and enrichment (lookups by email, LinkedIn URL, domain or phone). Solo is paced every 5 hours and every week; Agency every day and every billing month; Platform to figures agreed in writing. The numbers are on pricing, and GET /v1/account shows yours with what each window has used. A pace belongs to the account, not to a person: everything your team members search, enrich and export counts in the same windows.

Reach a window and calls of that kind are paced to one request a minute until it resets — the other kind keeps running at full speed. Every answer then carries X-Quota-State: paced and X-Quota-Reset in the headers, and on every endpoint except the three v2 contact-point doors a meta.notice in the body too, with code: fair_use_paced, the kind, the window, windowLimit, windowUsed, resetsAt and a support contact. Those three answer with data and no meta at all, by design — which is why the reset is in a header rather than only in the body. Either way your code can tell a pace from an outage without guessing, and knows exactly when it ends.

A call that costs no records is never paced: a count, a breakdown, an enrichment that finds nobody and an empty page all keep answering at full speed, however far past a window you are. The exception is the v2 contact lookups (work email, personal email, phone, reverse): they cost one record per call, found or not. A search page is trimmed to whatever is left in the window rather than overshooting.

Bulk exports count too. An export's rows count against the search windows, and the rows it enriched against the enrichment windows — every window, on top of the export ceilings themselves. A large export day is therefore a large search day for the pace. On Solo it works differently: export rows count against the weekly enrichment allowance (50k a week, shared with API enrichments) instead of the search windows and the 5-hour enrichment window, so one Solo export can be as large as the week has left, up to 50,000 rows.

Older paid plans with a monthly records figure are paced the same way once past it, to their billing date, with X-Quota-State: over-limit and code: fair_use_throttled instead.

The free plan is refused once its 1,000 records are spent — 402, with the same wording. Those 1,000 do not come back, so a 402 on Free means upgrade rather than wait.

Do not retry into a pace. The answer says what is happening and when it ends. Surface it to whoever owns the account instead of looping — or write to support, who raise a pace for a real workload.

Errors

Success is { success: true, data, meta }; failure is { success: false, error: { message, details? } }. The shape never varies, so one error branch handles every endpoint.

StatusMeaning
400Validation failed — details names the fields that were wrong.
401Missing, wrong or revoked key.
402Free plan: the 1,000 records are spent. They are a one-off allowance and do not reset — upgrade to keep going.
403The key lacks the scope for that endpoint, or the account is suspended.
404No matching person or company. Costs nothing.
429Faster than your plan's rate, or a fair-use window reached — then 1 a minute until it resets, and X-Quota-State says which. Honour Retry-After.
503The store behind that capability is temporarily unreachable — the body names which one (code: no_source). Transient: retry with backoff. Never billed.
A 503 is transient. The store behind that capability is unreachable right now rather than missing, and the body names which one under code: no_source. Back off and retry; it is never billed.

Response headers

HeaderWhenMeaning
X-Request-IdEvery responseQuote it in a support request and we can find the exact call. Send your own and we will echo it.
X-SourceEvery data responseThe dataset that answered, under its public name — leadocean for live data. Supplier names never leave the API.
X-RateLimit-Limit429s and paced answersThe allowance in force: your plan's requests a second normally, 1 a minute while paced.
X-RateLimit-Policy429s and paced answersHow it is paced — 50;w=1 on Solo, 200;w=1 on Agency, or 1;w=60 while a window is reached.
X-Quota-StateWhile pacedpaced — a fair-use window is reached; or over-limit — an older plan is past its monthly records. The one header to alert on.
X-Quota-ResetWhile pacedWhen the window, or the allowance, resets — ISO 8601. The piece your code can act on.
X-Quota-ContactWhile pacedWhere to write to have the pace raised.
Retry-AfterEvery 429Seconds to wait — 1 for the rate limit, 60 while paced.

Checking your usage

GET /v1/account · free

The whole account in one read. Your plan and whether it is fair use, records used, remaining and when they reset, what happens past the ceiling (whenOver: throttled on a paid plan, refused on Free), your pace — every window with its limit, what it has used and when it resets, and pace.paced naming the one that is slowing you now, if any — an active grant, the subscription state (status and period end — never invoices or card details), today's and this period's export rows against their ceilings, and your rate. Read it before a large job, or after a 402 or 429, instead of guessing. Over MCP the same document is leadocean_get_account.

GET /v1/usage · free

Returns used for the current period, the period it follows (lifetime on Free, billing on a paid plan), resetsAt, your plan, and daily and perKey totals for the last 30 days — enough to put a usage chart in your own dashboard, or to alert before you hit the ceiling rather than after. Your account shows the same numbers.

Reference endpoints are free too: GET https://api.leadocean.io/v1/filters and GET https://api.leadocean.io/v1/enums/<name> are public and need no key at all.