Documentation
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.
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. A count=true with any larger limit is an ordinary page you pay for, with the total attached.
| Call | Costs | Notes |
|---|---|---|
| A search page of 25 | 25 records | One per person or company handed back. Ask for fewer and you are charged for fewer. |
| Enriching one person | 1 record | The same whether or not you reveal emails and phone numbers. |
| One company lookup | 1 record | The same whether you came in by domain or LinkedIn URL. |
| A 404 — nobody matched | nothing | You are only charged for records you actually receive. |
| A 429, a 402 or a 503 | nothing | Rejected requests are never metered. |
| GET /v1/filters, /v1/enums, /v1/usage | nothing | Reference and account endpoints are free. |
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's records come back on its billing date — the day of the month you subscribed, not the 1st. Free gets one key, Pro five — see pricing.
100 requests per second per key, paced evenly rather than allowed in one burst at the top of each second. Over that you get 429 with Retry-After: 1. The limit is per key, so splitting a job across several keys on a Pro plan raises your ceiling.
limit goes up to 100 records per search request, so 100 requests a second is a much larger number of records a second than it sounds — ask for full pages rather than making more calls.
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.
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.
A paid account is never cut off. Past your records you are paced to one request a minute until they come back on your billing date. Every answer then carries X-Quota-State: over-limit 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_throttled, a message, resetsAt and a support contact. Those three answer with data and no meta at all, by design — which is why the reset date is in a header rather than only in the body. Either way your code can tell a throttle from an outage without guessing, and knows exactly when it ends.
A search page is trimmed to whatever is left rather than overshooting: ask for 25 with 8 remaining and you get 8, not an error and not a bill for 25.
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.
Success is { success: true, data, meta }; failure is { success: false, error: { message, details? } }. The shape never varies, so one error branch handles every endpoint.
| Status | Meaning |
|---|---|
| 400 | Validation failed — details names the fields that were wrong. |
| 401 | Missing, wrong or revoked key. |
| 402 | Free plan: the 1,000 records are spent. They are a one-off allowance and do not reset — upgrade to keep going. |
| 403 | The key lacks the scope for that endpoint, or the account is suspended. |
| 404 | No matching person or company. Costs nothing. |
| 429 | Faster than your rate — 100 a second, or 1 a minute once a paid account is past its records. Honour Retry-After. |
| 503 | The store behind that capability is temporarily unreachable — the body names which one (code: no_source). Transient: retry with backoff. Never billed. |
code: no_source. Back off and retry; it is never billed.| Header | When | Meaning |
|---|---|---|
| X-Request-Id | Every response | Quote it in a support request and we can find the exact call. Send your own and we will echo it. |
| X-Source | Every data response | The dataset that answered, under its public name — leadocean for live data. Supplier names never leave the API. |
| X-RateLimit-Limit | 429s and throttled answers | The allowance in force: 100 a second normally, 1 a minute while throttled. |
| X-RateLimit-Policy | 429s and throttled answers | How it is paced — 100;w=1, or 1;w=60 while throttled. |
| X-Quota-State | Once past your records | over-limit. The one header to alert on. |
| X-Quota-Contact | Once past your records | Where to write to have the limit raised. |
| Retry-After | Every 429 | Seconds to wait — 1 for the rate limit, 60 while throttled. |
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), 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 Pro), 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.