Documentation
The hosted server at https://api.leadocean.io/mcp gives any MCP client the same data the REST API does — over OAuth 2.1, so there is no key to paste and nothing to leak into a chat log.
The server speaks Streamable HTTP with OAuth 2.1. You add one URL in your client, it sends you to LeadOcean to sign in, you approve, and the tools appear. Your assistant never sees an API key.
A few clients cannot sign in to a custom server: the ChatGPT desktop app, and Codex on a machine with no browser. They send a LeadOcean API key instead, as Authorization: Bearer <key> (or X-API-Key). The key keeps its own scopes and limits, records are billed to it, and you can pause or revoke it under API keys.
A connection is tied to your account, and usage counts against the same records as the REST API — one balance, however you call it. You can see and revoke every connected app from API keys → Connected apps in your account.
https://api.leadocean.io/mcp — that is the whole configuration. Everything below is just where each app wants you to paste it.Tools are tuned for an agent rather than a browser: records come back slim by default (a third of the full size; pass slim: false for everything), people searches default to addresses worth sending to and say so, leadocean_count_companies and leadocean_count_leads size a market for free before any record is spent, and leadocean_get_account tells the agent what the account has left. The catalog below is read live from the server.
| Client | How to add it |
|---|---|
| Claude | Settings → Connectors → Add custom connector → paste the URL → Connect. |
| ChatGPT (web) | chatgpt.com/plugins → + → Add custom MCP server → paste the URL under Connection, authentication OAuth → Create as a plugin, then install it and pick it with @ in a chat. |
| ChatGPT (desktop app) | Settings → Plugins → MCPs → Add → Connect to a custom MCP → type Streamable HTTP, paste the URL, and add the header Authorization: Bearer <your API key>. The desktop app has no OAuth option. |
| Grok | grok.com/connectors → New Connector → Custom → paste the URL → sign in. One connector works on the web, iPhone and Android. |
| Claude Code | claude mcp add --transport http leadocean https://api.leadocean.io/mcp then claude mcp login leadocean. |
| Cursor | mcp.json: {"mcpServers":{"leadocean":{"url":"https://api.leadocean.io/mcp"}}} |
| Codex | config.toml: [mcp_servers.leadocean] url = "https://api.leadocean.io/mcp" then codex mcp login leadocean. Without a browser, add bearer_token_env_var = "LEADOCEAN_API_KEY" and set that variable to your API key. |
| VS Code | .vscode/mcp.json: {"servers":{"leadocean":{"type":"http","url":"https://api.leadocean.io/mcp"}}} |
| Windsurf | mcp_config.json with serverUrl set to the URL above. |
| Gemini CLI | settings.json with httpUrl set to the URL above, then /mcp auth leadocean. |
Any client that supports remote MCP over HTTP will work, whether or not it is listed — there is nothing client-specific about the server.
These are the exact descriptions the server gives the model, read live from the running server — so an agent can plan its work without ever reading this page.
leadocean_list_enum_values · Resolve enum values · freeLook up the exact strings a closed-list filter accepts. Industry has 534 values and country 254, so guessing fails: search here first, then pass the exact value to leadocean_search_leads or leadocean_search_companies. Free, and it never spends records.
| Input | Type | Meaning |
|---|---|---|
| name | enum | Which value set to read — ONE name per call. |
| q | string | Substring to search for, e.g. "software" or "germany". Omit to list from the start. |
| limit | int | How many values to return (default 50, max 200). |
leadocean_list_filters · List filters & schemas · freeReturns every filter that leadocean_search_leads and leadocean_count_leads accept, the exact enum values allowed (seniority, emailStatus, company size codes), the names of the response schemas (leadocean.person.v1, leadocean.company.v1) and which data sources are currently active. Free — call it once when you are unsure which values are valid instead of guessing.
leadocean_search_leads · Search leads (people) · 1 recordFind people by job title, seniority, country, industry, company domain, company size or free text. Returns up to `limit` THIN person records (leadocean.person.v1 projection): full name, headline, current job title and company (name, domain, industry, size), location (city, country), profile URL and the has_email / email_status / email_type flags — never email addresses or phone numbers (use leadocean_get_lead with reveal_email for those). Combine filters to narrow, e.g. title="CTO", seniority=["c_suite"], country=["DE"], minEmployees=50. Paginate with `cursor` (meta.nextCursor). Each returned record counts 1 against the monthly records quota (limit=25 → up to 25); the page is capped to what is left this month. Every row carries meta.source_ids.person_id (the record — pass it to leadocean_get_lead) and meta.source_ids.person_group_id (the person — equal across duplicate records of one human; compare it, never look it up). meta.unsupportedFilters lists any filter the active source ignored. By default this searches only people whose best email is `verified` or `catch_all` — the addresses worth sending to. To widen it, pass `emailStatus` yourself (the full enum opts out entirely, `["verified"]` narrows further), or pass `hasEmail` or `reachable`; any one of those replaces the default rather than adding to it. Paging is capped: one search pages through 10,000 rows by default, and on the page that reaches the cap meta.nextCursor is null and meta.depthCapped is true. That walk is over — retrying the same query returns no further cursors, and paging harder is never the fix. Narrow the filters and run several smaller searches instead (split by country, then industry, then headcount band, then title). The figure is per account: an account with a genuine large export to run can have it raised, so tell the user to ask support rather than looping around it. It counts rows PAGED THROUGH and is not the monthly records allowance, which is a separate limit and unaffected. The cursor itself is opaque and signed: pass back exactly the string meta.nextCursor gave you, unchanged. A cursor that has been edited, truncated or built by hand, or one minted for a different search, is refused with 400 "Invalid cursor"; so is any cursor issued before 2026-09-19, in which case start that query again from the first page. Do not store a cursor for later — it is a position in one walk, not a handle on a result set.
| Input | Type | Meaning |
|---|---|---|
| q | string | Free text over name, headline, job title and company. A short query needs every word; a longer one needs most of them, so a five-word phrase behaves as a keyword search rather than an exact match. Prefer the structured filters below. |
| profileKeywords | string[] | The same as keywords — the person’s own profile text; kept under this name for clients that adopted it. |
| excludeProfileKeywords | string[] | Profile keywords to exclude. |
| title | string[] | Job title keywords, e.g. ["Head of Sales","VP Sales"]. Wrap a value in [brackets] for an exact match. |
| excludeTitle | string[] | Job titles to exclude, e.g. ["assistant","intern"]. |
| excludeViewed | boolean | Leave out the people this account marked viewed (POST /v1/people/viewed) in viewedSet; exact for a list up to 20,000, a skip-ahead walk beyond (see meta.excludedViewed, meta.walkCapped). |
| viewedSet | string | Which viewed list excludeViewed reads, e.g. one per end-client workspace; default "default". |
| excludeIds | string[] | person_ids to leave out, e.g. the people you already showed, so a re-run brings new ones. Take each from a row's person_id (meta.source_ids.person_id). At most 1,000 per call. |
| seniority | enum[] | LeadOcean seniority band (finer than jobLevel). |
| jobLevel | enum[] | Seniority band of the current role. |
| jobFunction | enum[] | Department of the current role. |
| country | enum[] | Where the person is, ISO 3166-1 alpha-2, e.g. ["US","DE"]. |
| continent | enum[] | Continent the person is in. |
| salesRegion | enum[] | Commercial region the person is in. |
| city | string[] | City keywords for the person. |
| excludeCity | string[] | Cities to exclude. |
| education | string[] | School, degree or year phrases, e.g. ["Stanford"]. |
| minConnections | int | Minimum LinkedIn connections on the person's profile, 0–500. |
| domain | string[] | Company website domains, e.g. ["stripe.com"]. |
| companyName | string[] | Company name phrase, e.g. ["auto parts"] (both words, adjacent). Wrap a value in [brackets] for an exact name: ["[Advance Auto Parts]"]. |
| excludeCompanyName | string[] | Company name phrases to exclude; [brackets] for exact. |
| companyLinkedin | string[] | Company LinkedIn URLs, e.g. ["https://www.linkedin.com/company/stripe"]. |
| industry | enum[] | Company industry — 534 values; resolve with leadocean_list_enum_values before guessing. |
| excludeIndustry | enum[] | Industries to exclude; same 534 values. |
| companyType | enum[] | Legal type of the company. |
| employeeRange | enum[] | Headcount bracket — cheaper and broader than minEmployees/maxEmployees. |
| minEmployees | int | Company headcount, lower bound — only records whose value we hold; one with no figure on file is never returned. |
| maxEmployees | int | Company headcount, upper bound — only records whose value we hold; one with no figure on file is never returned. |
| minFounded | int | Year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| maxFounded | int | Latest year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| minFollowers | int | Minimum company LinkedIn followers — 0 means no minimum; any value of 1 or more matches only records whose figure we hold — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| fundingType | enum[] | Type of the last funding round — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| minFunding | int | Total funding raised, USD — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| maxFunding | int | Total funding raised, USD ceiling — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| minLastFundingYear | int | Funded no earlier than this year — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| maxLastFundingYear | int | Funded no later than this year — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| investors | string[] | Lead investor name keywords, e.g. ["Sequoia"]. |
| sic | string[] | SIC industry codes. |
| naicsSector | enum[] | Two-digit NAICS sector, e.g. ["42"] for Wholesale Trade — the coarse cut for market sizing; 18 values, resolve with leadocean_list_enum_values({ name: "naics_sector" }). On companies it is the DERIVED sector, the one the record shows. On people it is the employer's first-listed sector as stored (a source value, held for about half of people), which can differ from the company record's derived sector until the people index is rebuilt. |
| keywords | string[] | Keywords in the person’s own profile: headline, summary, skills and job descriptions — the PERSON’s text, not the employer’s (for the company’s text search companies, or filter people by industry / companyName). Each value is a phrase whose words must all appear; several values OR together. |
| excludeKeywords | string[] | Profile keywords to exclude. |
| companyKeywords | string[] | What the EMPLOYER does, in its own words: each value is a phrase whose words must all appear in the company’s description, specialties, tags or name — or an exact industry label, which then matches every company filed under it; several values OR together. The broad way to ask for "people at cybersecurity companies": an industry label alone misses most of them — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| hqCountry | enum[] | Company headquarters country, ISO 3166-1 alpha-2. |
| hqCity | string[] | Company headquarters city keywords — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| hqState | string[] | Company headquarters state or region — a US state, Canadian province, Australian state or German Land also matches its other spellings ("TX" finds "Texas", "Bayern" finds "Bavaria"), at companies in that country only; add hqCountry to pin an ambiguous code such as WA — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| hqContinent | enum[] | Continent of the company headquarters. |
| hqSalesRegion | enum[] | Commercial region of the company headquarters. |
| technologies | string[] | Technologies detected on the company website (LeadOcean data only). |
| technologyCategories | enum[] | What the detected technology is for, e.g. Analytics or CDN, rather than its name (own data only; covers the ~7.8M crawled companies). |
| emailStatus | enum[] | Email deliverability (LeadOcean data only). |
| emailType | enum[] | Work or personal email (LeadOcean data only). Pair with emailStatus to ask for a deliverable WORK address. |
| hasEmail | boolean | true = only people with a known email, false = only those without (LeadOcean data only). |
| hasPhone | boolean | Only people with, or without, a known phone number (own data only). |
| reachable | enum | Holding an email OR a phone — `strict` additionally requires the email to be verified, catch_all_valid or catch_all. |
| slim | boolean | Default TRUE here: empty fields, the picture block and the duplicate email_types list are dropped. Pass false for the full thin record. |
| fields | string[] | Keep only these dotted paths, e.g. ["profile_data.profile_full_name","contact_data.contact_current_experiences","meta.source_ids"]. Applied after slim. |
| facetCompanies | boolean | With facets: also count distinct employers per bucket (estimate). Off by default — slower on a wide filter. |
| cursor | string | Opaque page token — pass meta.nextCursor from the previous call back, exactly as it was returned, to get the next page. It is signed: an edited, truncated or hand-built cursor, or one from a different search, is refused with 400 "Invalid cursor". Null nextCursor means there are no more pages, either because the results ran out or because the search hit its depth cap (meta.depthCapped). |
| limit | int | Records per page, 1–100 (default 25); up to 200 on order=stable for an account enabled for unlimited walks. |
| order | enum | ranked (default): best matches first. stable: every match in id order on one pinned snapshot, for walking a whole result set — keep passing order=stable with each cursor. A stable cursor cannot continue a ranked search or the other way round; a 410 means the snapshot was retired mid-walk, so start again without a cursor. Accounts enabled for unlimited walks page a stable walk to its end, up to 200 rows a page; everyone else keeps the normal depth and 100 rows. |
| facets | boolean | Also return counts per seniority / country / industry where the source supports it. |
leadocean_count_leads · Count leads · freeEstimate how many people match a set of filters BEFORE pulling pages — use it to size an audience or check that a filter combination is not empty. Same filters as leadocean_search_leads. Returns the total and `totalIsExact` (read from the engine — false only if it reports a floor rather than an exact count, in which case the total is a minimum), `distinctCompanies` — how many employers the matched people span (exact below 40,000, a close estimate above; `distinctCompaniesIsExact` says which) — a one-record sample count, whether more pages exist, and facet counts; with facetCompanies=true each bucket also carries `companies` (employers, estimated). For how many COMPANIES match company filters, use leadocean_count_companies instead. FREE: sizing an audience spends no records, however many times you ask. Pass facets=false for just the number, which is far quicker on a wide filter. By default this searches only people whose best email is `verified` or `catch_all` — the addresses worth sending to. To widen it, pass `emailStatus` yourself (the full enum opts out entirely, `["verified"]` narrows further), or pass `hasEmail` or `reachable`; any one of those replaces the default rather than adding to it. The total therefore describes the mailable audience, not everyone matching the other filters — say so when you report it; `totalAll` beside it is the same filters with no email condition, so the gap is visible.
| Input | Type | Meaning |
|---|---|---|
| q | string | Free text over name, headline, job title and company. A short query needs every word; a longer one needs most of them, so a five-word phrase behaves as a keyword search rather than an exact match. Prefer the structured filters below. |
| profileKeywords | string[] | The same as keywords — the person’s own profile text; kept under this name for clients that adopted it. |
| excludeProfileKeywords | string[] | Profile keywords to exclude. |
| title | string[] | Job title keywords, e.g. ["Head of Sales","VP Sales"]. Wrap a value in [brackets] for an exact match. |
| excludeTitle | string[] | Job titles to exclude, e.g. ["assistant","intern"]. |
| excludeViewed | boolean | Leave out the people this account marked viewed (POST /v1/people/viewed) in viewedSet; exact for a list up to 20,000, a skip-ahead walk beyond (see meta.excludedViewed, meta.walkCapped). |
| viewedSet | string | Which viewed list excludeViewed reads, e.g. one per end-client workspace; default "default". |
| excludeIds | string[] | person_ids to leave out, e.g. the people you already showed, so a re-run brings new ones. Take each from a row's person_id (meta.source_ids.person_id). At most 1,000 per call. |
| seniority | enum[] | LeadOcean seniority band (finer than jobLevel). |
| jobLevel | enum[] | Seniority band of the current role. |
| jobFunction | enum[] | Department of the current role. |
| country | enum[] | Where the person is, ISO 3166-1 alpha-2, e.g. ["US","DE"]. |
| continent | enum[] | Continent the person is in. |
| salesRegion | enum[] | Commercial region the person is in. |
| city | string[] | City keywords for the person. |
| excludeCity | string[] | Cities to exclude. |
| education | string[] | School, degree or year phrases, e.g. ["Stanford"]. |
| minConnections | int | Minimum LinkedIn connections on the person's profile, 0–500. |
| domain | string[] | Company website domains, e.g. ["stripe.com"]. |
| companyName | string[] | Company name phrase, e.g. ["auto parts"] (both words, adjacent). Wrap a value in [brackets] for an exact name: ["[Advance Auto Parts]"]. |
| excludeCompanyName | string[] | Company name phrases to exclude; [brackets] for exact. |
| companyLinkedin | string[] | Company LinkedIn URLs, e.g. ["https://www.linkedin.com/company/stripe"]. |
| industry | enum[] | Company industry — 534 values; resolve with leadocean_list_enum_values before guessing. |
| excludeIndustry | enum[] | Industries to exclude; same 534 values. |
| companyType | enum[] | Legal type of the company. |
| employeeRange | enum[] | Headcount bracket — cheaper and broader than minEmployees/maxEmployees. |
| minEmployees | int | Company headcount, lower bound — only records whose value we hold; one with no figure on file is never returned. |
| maxEmployees | int | Company headcount, upper bound — only records whose value we hold; one with no figure on file is never returned. |
| minFounded | int | Year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| maxFounded | int | Latest year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| minFollowers | int | Minimum company LinkedIn followers — 0 means no minimum; any value of 1 or more matches only records whose figure we hold — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| fundingType | enum[] | Type of the last funding round — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| minFunding | int | Total funding raised, USD — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| maxFunding | int | Total funding raised, USD ceiling — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| minLastFundingYear | int | Funded no earlier than this year — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| maxLastFundingYear | int | Funded no later than this year — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| investors | string[] | Lead investor name keywords, e.g. ["Sequoia"]. |
| sic | string[] | SIC industry codes. |
| naicsSector | enum[] | Two-digit NAICS sector, e.g. ["42"] for Wholesale Trade — the coarse cut for market sizing; 18 values, resolve with leadocean_list_enum_values({ name: "naics_sector" }). On companies it is the DERIVED sector, the one the record shows. On people it is the employer's first-listed sector as stored (a source value, held for about half of people), which can differ from the company record's derived sector until the people index is rebuilt. |
| keywords | string[] | Keywords in the person’s own profile: headline, summary, skills and job descriptions — the PERSON’s text, not the employer’s (for the company’s text search companies, or filter people by industry / companyName). Each value is a phrase whose words must all appear; several values OR together. |
| excludeKeywords | string[] | Profile keywords to exclude. |
| companyKeywords | string[] | What the EMPLOYER does, in its own words: each value is a phrase whose words must all appear in the company’s description, specialties, tags or name — or an exact industry label, which then matches every company filed under it; several values OR together. The broad way to ask for "people at cybersecurity companies": an industry label alone misses most of them — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| hqCountry | enum[] | Company headquarters country, ISO 3166-1 alpha-2. |
| hqCity | string[] | Company headquarters city keywords — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| hqState | string[] | Company headquarters state or region — a US state, Canadian province, Australian state or German Land also matches its other spellings ("TX" finds "Texas", "Bayern" finds "Bavaria"), at companies in that country only; add hqCountry to pin an ambiguous code such as WA — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| hqContinent | enum[] | Continent of the company headquarters. |
| hqSalesRegion | enum[] | Commercial region of the company headquarters. |
| technologies | string[] | Technologies detected on the company website (LeadOcean data only). |
| technologyCategories | enum[] | What the detected technology is for, e.g. Analytics or CDN, rather than its name (own data only; covers the ~7.8M crawled companies). |
| emailStatus | enum[] | Email deliverability (LeadOcean data only). |
| emailType | enum[] | Work or personal email (LeadOcean data only). Pair with emailStatus to ask for a deliverable WORK address. |
| hasEmail | boolean | true = only people with a known email, false = only those without (LeadOcean data only). |
| hasPhone | boolean | Only people with, or without, a known phone number (own data only). |
| reachable | enum | Holding an email OR a phone — `strict` additionally requires the email to be verified, catch_all_valid or catch_all. |
| facets | boolean | Break the total down by seniority, country, industry and company size. On by default. The breakdown is the slow part of this call — four aggregations over the matched set — so pass false when you only want the number and it returns in well under a second. |
| facetCompanies | boolean | Also count distinct employers inside each facet bucket (`companies` beside `count`, an estimate within ~1%). For NARROW audiences — a few million people or fewer; on a broad one the per-bucket counts time out and the call answers without them, with facetCompaniesWithheld saying so. Off by default. distinctCompanies at the top level is returned for any filtered count; with no filter at all (the whole database) it is null — counting every employer there is too slow to answer. |
leadocean_get_lead · Get lead (enrich one person) · 1 recordEnrich ONE specific person. Pass a LinkedIn profile URL (preferred), a work email, or — when the person came from leadocean_search_leads — the person_id that row carries at meta.source_ids.person_id, which is the only identifier that works for the roughly one person in five who has no LinkedIn URL. The same row carries meta.source_ids.person_group_id: person_id names a RECORD, person_group_id names the PERSON as far as our deduplication knows — two records with the same person_group_id are one human, whichever key you reached them by. Compare it; do not look it up. Returns the full leadocean.person.v1 record: profile_data (identity, headline, summary, location, picture, languages, expertises, social links in profile_social_links, tags), contact_data (current experiences with company details and the start_date of the role, still-at-company status, has_email / email_status / email_type flags; email addresses and phones ONLY when reveal_email=true), and resume_data: experiences (PAST roles — job_title, company_name, start_date, end_date, job_seniority.job_level and priority, in the order the profile lists them; company_id is null because past employers are not yet linked to company records, so name the company rather than looking it up), educations (school, diploma, specialization, start and end dates), certifications (name, authority), awards (name, issue — the issuer — and date), publications, memberships, patents and r_skills (skill names), each filled when we hold it and empty when we do not. The current role is in contact_data.contact_current_experiences and is NOT repeated in resume_data.experiences. Not for discovery — use leadocean_search_leads to find people first. Counts as 1 record, with or without reveal_email.
| Input | Type | Meaning |
|---|---|---|
| linkedin_url | url | LinkedIn profile URL, e.g. https://www.linkedin.com/in/jane-doe (preferred key). |
| Work email address — used when no LinkedIn URL is known. | ||
| phone | string | Phone number in any common format — the reverse lookup: who is this number. The REST API has always accepted it; this tool used to strip it and then answer "phone is required", which is the opposite of the truth. |
| person_id | string | The id a search row already handed you: meta.source_ids.person_id on any leadocean_search_leads result. Pass it straight back to enrich that exact person — this is the tool to reach for after a search, because it saves carrying an identifier between the two calls. It is a translation rather than a fourth key: the person is looked up by id and the enrichment then runs on the identifier their own record holds, so it is the same record, the same one-record price, the same cached answer and the same meta.key_hash as passing that identifier yourself. Reach for it in particular when a search row has no profile_url — about a fifth of the people search can find have no LinkedIn URL, and search publishes email FLAGS and never an address, so for those people this is the only identifier you can hold. Digits only, as returned. One 404 only: nobody carries that id (a typo, or a row from an older index). A person we hold with no contact record comes back with their profile and résumé, contact fields empty and meta.contactRecord false, for one record — so has_email and has_phone both false on a search row means you get the profile without contact fields. |
| reveal_email | boolean | true = include every contact point we hold — email addresses AND phone numbers — in contact_data. Despite the name it governs BOTH; for phones alone, leadocean_find_phone is the tool to reach for. Costs no extra credit: one enrichment is one record either way. Left out, it is true when you look the person up by email and false otherwise; send false to withhold them. |
leadocean_find_phone · Find phone number · 1 recordGet the PHONE NUMBERS we hold for ONE person. Pass a LinkedIn profile URL (preferred), a work email, a phone number you already have, or the person_id a leadocean_search_leads row carries at meta.source_ids.person_id. Returns has_phone plus every number, each with its type (mobile/direct/office) and priority — best first. has_phone: false means we genuinely hold none, not that the lookup failed. Pair it with leadocean_search_leads: search with hasPhone=true (or reachable) to find people who HAVE a number, which costs nothing extra, then call this for the ones you want. Counts as 1 record, the same as an enrichment — this is the same lookup under a name you can find, so calling it instead of leadocean_get_lead costs nothing more. Not for discovery: it answers about a person you can already name.
| Input | Type | Meaning |
|---|---|---|
| linkedin_url | url | LinkedIn profile URL, e.g. https://www.linkedin.com/in/jane-doe (preferred key). |
| Work email address — used when no LinkedIn URL is known. | ||
| phone | string | A number you already hold, to find the rest we have for that person. |
| person_id | string | The id a search row already handed you: meta.source_ids.person_id on any leadocean_search_leads result. Search with hasPhone=true to find people who HAVE a number, then pass each row's person_id here — nothing to carry between the two calls, and it works for the rows with no profile_url, which is about one person in five. It is a translation rather than a fourth key: the person is looked up by id and the lookup then runs on the identifier their own record holds, so it is the same numbers, the same one-record price and the same meta.key_hash as passing that identifier yourself. Digits only, as returned. Two distinct 404s: nobody carries that id, or the person exists and we hold no identifier we can enrich by for them — the second says so plainly and will not change on a retry. |
leadocean_search_companies · Search companies · 1 recordFind companies rather than people: industry, headcount, revenue, funding, technologies, headquarters. Returns leadocean.company.v1 records, and meta.total is the exact number of matching companies on every page (counted once, on the first). Use it to build an account list first, then pass a domain to leadocean_search_leads to find the people inside. Each company returned counts one record. Paginate with `cursor` (meta.nextCursor). Paging is capped: one search pages through 10,000 rows by default, and on the page that reaches the cap meta.nextCursor is null and meta.depthCapped is true. That walk is over — retrying the same query returns no further cursors, and paging harder is never the fix. Narrow the filters and run several smaller searches instead (split by country, then industry, then headcount band, then title). The figure is per account: an account with a genuine large export to run can have it raised, so tell the user to ask support rather than looping around it. It counts rows PAGED THROUGH and is not the monthly records allowance, which is a separate limit and unaffected. The cursor itself is opaque and signed: pass back exactly the string meta.nextCursor gave you, unchanged. A cursor that has been edited, truncated or built by hand, or one minted for a different search, is refused with 400 "Invalid cursor"; so is any cursor issued before 2026-09-19, in which case start that query again from the first page. Do not store a cursor for later — it is a position in one walk, not a handle on a result set.
| Input | Type | Meaning |
|---|---|---|
| q | string | Free text over name, headline, job title and company. A short query needs every word; a longer one needs most of them, so a five-word phrase behaves as a keyword search rather than an exact match. Prefer the structured filters below. |
| name | string[] | Company name phrase, e.g. ["auto parts"] (both words, adjacent). Wrap a value in [brackets] for an exact name: ["[Advance Auto Parts]"]. |
| excludeName | string[] | Company name phrases to exclude; [brackets] for exact. |
| domain | string[] | Company website domains, e.g. ["stripe.com"]. |
| string[] | Company LinkedIn URLs — resolved through the people we hold at the company (most real companies); a URL nobody works at is a 404 pointing at GET /v1/companies/enrich?linkedin_url=…, which always works. | |
| industry | enum[] | Company industry — 534 values; resolve with leadocean_list_enum_values before guessing. |
| excludeIndustry | enum[] | Industries to exclude; same 534 values. |
| companyType | enum[] | Legal type of the company. |
| employeeRange | enum[] | Headcount bracket — cheaper and broader than minEmployees/maxEmployees. |
| minEmployees | int | Company headcount, lower bound — only records whose value we hold; one with no figure on file is never returned. |
| maxEmployees | int | Company headcount, upper bound — only records whose value we hold; one with no figure on file is never returned. |
| minRevenue | int | Annual revenue floor in USD — only records whose value we hold; one with no figure on file is never returned. |
| maxRevenue | int | Annual revenue ceiling in USD — only records whose value we hold; one with no figure on file is never returned. |
| minFollowers | int | Minimum company LinkedIn followers — 0 means no minimum; any value of 1 or more matches only records whose figure we hold. |
| minFounded | int | Earliest year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| maxFounded | int | Latest year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| fundingType | enum[] | Type of the most recent funding round. |
| minFunding | int | Total funding raised, USD floor — only records whose value we hold; one with no figure on file is never returned. |
| maxFunding | int | Total funding raised, USD ceiling — only records whose value we hold; one with no figure on file is never returned. |
| minLastFundingYear | int | Funded no earlier than this year — only records whose value we hold; one with no figure on file is never returned. |
| maxLastFundingYear | int | Funded no later than this year — only records whose value we hold; one with no figure on file is never returned. |
| investors | string[] | Lead investor name keywords, e.g. ["Sequoia"]. |
| naics | string[] | NAICS industry codes, e.g. ["5415"] — matches any code the company lists. |
| naicsPrimary | string[] | The one NAICS code a company is filed under, e.g. ["423120"] — use for sizing by sector; naics matches any listed code. |
| naicsSector | enum[] | Two-digit NAICS sector, e.g. ["42"] for Wholesale Trade — the coarse cut for market sizing; 18 values, resolve with leadocean_list_enum_values({ name: "naics_sector" }). On companies it is the DERIVED sector, the one the record shows. On people it is the employer's first-listed sector as stored (a source value, held for about half of people), which can differ from the company record's derived sector until the people index is rebuilt. |
| sic | string[] | SIC industry codes. |
| keywords | string[] | Keywords across company description, specialties, tags and name: each value is a phrase whose words must all appear — or an exact industry label, which then matches every company filed under it; several values OR together. |
| excludeKeywords | string[] | Company keywords (or exact industry labels) to exclude. |
| hqCountry | enum[] | Company headquarters country, ISO 3166-1 alpha-2. |
| hqCity | string[] | Company headquarters city keywords. |
| hqState | string[] | Company headquarters state or region — a US state, Canadian province, Australian state or German Land also matches its other spellings ("TX" finds "Texas", "Bayern" finds "Bavaria"), at companies in that country only; add hqCountry to pin an ambiguous code such as WA. |
| hqContinent | enum[] | Continent of the company headquarters. |
| hqSalesRegion | enum[] | Commercial region of the company headquarters. |
| technologies | string[] | Technologies detected on the company website (LeadOcean data only). |
| technologyCategories | enum[] | What the detected technology is for, e.g. Analytics or CDN, rather than its name (own data only; covers the ~7.8M crawled companies). |
| hasMailableContacts | boolean | True = companies with at least one person whose best email is verified, catch_all_valid or catch_all; false = companies with none (LeadOcean data only). |
| slim | boolean | Default TRUE here: each record comes without its technology list (the count stays), tags, specialties, financials and empty fields — about a third of the full size. Pass false for the full leadocean.company.v1 record. |
| fields | string[] | Keep only these dotted paths, e.g. ["company_data.company_name","company_data.company_domain","meta.source_ids"]. Applied after slim. |
| count | boolean | Also return the exact total in meta.total. With limit 1 the call is free and returns no rows (meta.countOnly) — but for sizing prefer leadocean_count_companies, which adds breakdowns. |
| cursor | string | Opaque page token from meta.nextCursor — pass it back exactly as returned. It is signed: an edited, truncated or hand-built cursor, or one from a different search, is refused with 400 "Invalid cursor". Null nextCursor means no more pages, either because the results ran out or because the search hit its depth cap (meta.depthCapped). |
| limit | int | Companies per page, 1–100 (default 25); up to 200 on order=stable for an account enabled for unlimited walks. |
| order | enum | ranked (default): best matches first. stable: every match in id order on one pinned snapshot, for walking a whole result set — keep passing order=stable with each cursor. A stable cursor cannot continue a ranked search or the other way round; a 410 means the snapshot was retired mid-walk, so start again without a cursor. Accounts enabled for unlimited walks page a stable walk to its end, up to 200 rows a page; everyone else keeps the normal depth and 100 rows. |
leadocean_count_companies · Count companies · freeCount distinct companies matching filters, with breakdowns by industry, headcount, country, state and NAICS. Free. Use this for market sizing and TAM, not count_leads, which counts people. Same filters as leadocean_search_companies; no email-status default is applied because it counts companies, not mailable people — pass hasMailableContacts: true for companies with someone you can write to. The total is exact; a filter that could not be applied is named in unsupportedFilters and the total is withheld rather than wrong.
| Input | Type | Meaning |
|---|---|---|
| q | string | Free text over name, headline, job title and company. A short query needs every word; a longer one needs most of them, so a five-word phrase behaves as a keyword search rather than an exact match. Prefer the structured filters below. |
| name | string[] | Company name phrase, e.g. ["auto parts"] (both words, adjacent). Wrap a value in [brackets] for an exact name: ["[Advance Auto Parts]"]. |
| excludeName | string[] | Company name phrases to exclude; [brackets] for exact. |
| domain | string[] | Company website domains, e.g. ["stripe.com"]. |
| string[] | Company LinkedIn URLs — resolved through the people we hold at the company (most real companies); a URL nobody works at is a 404 pointing at GET /v1/companies/enrich?linkedin_url=…, which always works. | |
| industry | enum[] | Company industry — 534 values; resolve with leadocean_list_enum_values before guessing. |
| excludeIndustry | enum[] | Industries to exclude; same 534 values. |
| companyType | enum[] | Legal type of the company. |
| employeeRange | enum[] | Headcount bracket — cheaper and broader than minEmployees/maxEmployees. |
| minEmployees | int | Company headcount, lower bound — only records whose value we hold; one with no figure on file is never returned. |
| maxEmployees | int | Company headcount, upper bound — only records whose value we hold; one with no figure on file is never returned. |
| minRevenue | int | Annual revenue floor in USD — only records whose value we hold; one with no figure on file is never returned. |
| maxRevenue | int | Annual revenue ceiling in USD — only records whose value we hold; one with no figure on file is never returned. |
| minFollowers | int | Minimum company LinkedIn followers — 0 means no minimum; any value of 1 or more matches only records whose figure we hold. |
| minFounded | int | Earliest year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| maxFounded | int | Latest year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| fundingType | enum[] | Type of the most recent funding round. |
| minFunding | int | Total funding raised, USD floor — only records whose value we hold; one with no figure on file is never returned. |
| maxFunding | int | Total funding raised, USD ceiling — only records whose value we hold; one with no figure on file is never returned. |
| minLastFundingYear | int | Funded no earlier than this year — only records whose value we hold; one with no figure on file is never returned. |
| maxLastFundingYear | int | Funded no later than this year — only records whose value we hold; one with no figure on file is never returned. |
| investors | string[] | Lead investor name keywords, e.g. ["Sequoia"]. |
| naics | string[] | NAICS industry codes, e.g. ["5415"] — matches any code the company lists. |
| naicsPrimary | string[] | The one NAICS code a company is filed under, e.g. ["423120"] — use for sizing by sector; naics matches any listed code. |
| naicsSector | enum[] | Two-digit NAICS sector, e.g. ["42"] for Wholesale Trade — the coarse cut for market sizing; 18 values, resolve with leadocean_list_enum_values({ name: "naics_sector" }). On companies it is the DERIVED sector, the one the record shows. On people it is the employer's first-listed sector as stored (a source value, held for about half of people), which can differ from the company record's derived sector until the people index is rebuilt. |
| sic | string[] | SIC industry codes. |
| keywords | string[] | Keywords across company description, specialties, tags and name: each value is a phrase whose words must all appear — or an exact industry label, which then matches every company filed under it; several values OR together. |
| excludeKeywords | string[] | Company keywords (or exact industry labels) to exclude. |
| hqCountry | enum[] | Company headquarters country, ISO 3166-1 alpha-2. |
| hqCity | string[] | Company headquarters city keywords. |
| hqState | string[] | Company headquarters state or region — a US state, Canadian province, Australian state or German Land also matches its other spellings ("TX" finds "Texas", "Bayern" finds "Bavaria"), at companies in that country only; add hqCountry to pin an ambiguous code such as WA. |
| hqContinent | enum[] | Continent of the company headquarters. |
| hqSalesRegion | enum[] | Commercial region of the company headquarters. |
| technologies | string[] | Technologies detected on the company website (LeadOcean data only). |
| technologyCategories | enum[] | What the detected technology is for, e.g. Analytics or CDN, rather than its name (own data only; covers the ~7.8M crawled companies). |
| hasMailableContacts | boolean | True = companies with at least one person whose best email is verified, catch_all_valid or catch_all; false = companies with none (LeadOcean data only). |
leadocean_get_company · Get company · 1 recordLook up ONE company by website domain (preferred) or LinkedIn company URL. Returns leadocean.company.v1: company_data (name, description, industry, headcount and size code in company_employees, LinkedIn follower count in company_linkedin_followers, headquarters address, founded year, website, social links), company_detected_technologies, and company_metrics (completion_score, marketability_score). Use it to qualify an account, or to get the domain before searching its people with leadocean_search_leads(domain=…). Counts as 1 record.
| Input | Type | Meaning |
|---|---|---|
| linkedin_url | url | LinkedIn company page, e.g. https://www.linkedin.com/company/stripe |
| domain | string | Website domain, e.g. "stripe.com" (preferred key). |
| slim | boolean | Default TRUE here: each record comes without its technology list (the count stays), tags, specialties, financials and empty fields — about a third of the full size. Pass false for the full leadocean.company.v1 record. |
| fields | string[] | Keep only these dotted paths, e.g. ["company_data.company_name","company_data.company_domain","meta.source_ids"]. Applied after slim. |
leadocean_export_leads · Start a bulk CSV export · 1 recordStart a bulk export of people as a plain CSV file — ASYNCHRONOUS. This tool returns at once with an export id and status "queued"; the file is NOT ready. Poll leadocean_get_export every pollAfter seconds until status is "done", then hand the user the download link it returns (do not try to read the CSV through a tool). BILLING: up to `limit` records are reserved on the account the moment this is accepted, and each written row is charged like a search result; a column outside the search row adds one enrichment per row. Refused up front, never silently capped: 400 when `limit` exceeds 50,000 or a filter cannot be applied, 429 export_limit_daily / export_limit_monthly with `remaining` and `resetsAt`, 402 when the account has fewer records left than the export needs. One export runs per account at a time; further ones queue. Always call leadocean_count_leads first and confirm the size with the user.
| Input | Type | Meaning |
|---|---|---|
| q | string | Free text over name, headline, job title and company. A short query needs every word; a longer one needs most of them, so a five-word phrase behaves as a keyword search rather than an exact match. Prefer the structured filters below. |
| profileKeywords | string[] | The same as keywords — the person’s own profile text; kept under this name for clients that adopted it. |
| excludeProfileKeywords | string[] | Profile keywords to exclude. |
| title | string[] | Job title keywords, e.g. ["Head of Sales","VP Sales"]. Wrap a value in [brackets] for an exact match. |
| excludeTitle | string[] | Job titles to exclude, e.g. ["assistant","intern"]. |
| excludeViewed | boolean | Leave out the people this account marked viewed (POST /v1/people/viewed) in viewedSet; exact for a list up to 20,000, a skip-ahead walk beyond (see meta.excludedViewed, meta.walkCapped). |
| viewedSet | string | Which viewed list excludeViewed reads, e.g. one per end-client workspace; default "default". |
| excludeIds | string[] | person_ids to leave out, e.g. the people you already showed, so a re-run brings new ones. Take each from a row's person_id (meta.source_ids.person_id). At most 1,000 per call. |
| seniority | enum[] | LeadOcean seniority band (finer than jobLevel). |
| jobLevel | enum[] | Seniority band of the current role. |
| jobFunction | enum[] | Department of the current role. |
| country | enum[] | Where the person is, ISO 3166-1 alpha-2, e.g. ["US","DE"]. |
| continent | enum[] | Continent the person is in. |
| salesRegion | enum[] | Commercial region the person is in. |
| city | string[] | City keywords for the person. |
| excludeCity | string[] | Cities to exclude. |
| education | string[] | School, degree or year phrases, e.g. ["Stanford"]. |
| minConnections | int | Minimum LinkedIn connections on the person's profile, 0–500. |
| domain | string[] | Company website domains, e.g. ["stripe.com"]. |
| companyName | string[] | Company name phrase, e.g. ["auto parts"] (both words, adjacent). Wrap a value in [brackets] for an exact name: ["[Advance Auto Parts]"]. |
| excludeCompanyName | string[] | Company name phrases to exclude; [brackets] for exact. |
| companyLinkedin | string[] | Company LinkedIn URLs, e.g. ["https://www.linkedin.com/company/stripe"]. |
| industry | enum[] | Company industry — 534 values; resolve with leadocean_list_enum_values before guessing. |
| excludeIndustry | enum[] | Industries to exclude; same 534 values. |
| companyType | enum[] | Legal type of the company. |
| employeeRange | enum[] | Headcount bracket — cheaper and broader than minEmployees/maxEmployees. |
| minEmployees | int | Company headcount, lower bound — only records whose value we hold; one with no figure on file is never returned. |
| maxEmployees | int | Company headcount, upper bound — only records whose value we hold; one with no figure on file is never returned. |
| minFounded | int | Year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| maxFounded | int | Latest year the company was founded — only records whose value we hold; one with no figure on file is never returned. |
| minFollowers | int | Minimum company LinkedIn followers — 0 means no minimum; any value of 1 or more matches only records whose figure we hold — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| fundingType | enum[] | Type of the last funding round — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| minFunding | int | Total funding raised, USD — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| maxFunding | int | Total funding raised, USD ceiling — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| minLastFundingYear | int | Funded no earlier than this year — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| maxLastFundingYear | int | Funded no later than this year — only records whose value we hold; one with no figure on file is never returned — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| investors | string[] | Lead investor name keywords, e.g. ["Sequoia"]. |
| sic | string[] | SIC industry codes. |
| naicsSector | enum[] | Two-digit NAICS sector, e.g. ["42"] for Wholesale Trade — the coarse cut for market sizing; 18 values, resolve with leadocean_list_enum_values({ name: "naics_sector" }). On companies it is the DERIVED sector, the one the record shows. On people it is the employer's first-listed sector as stored (a source value, held for about half of people), which can differ from the company record's derived sector until the people index is rebuilt. |
| keywords | string[] | Keywords in the person’s own profile: headline, summary, skills and job descriptions — the PERSON’s text, not the employer’s (for the company’s text search companies, or filter people by industry / companyName). Each value is a phrase whose words must all appear; several values OR together. |
| excludeKeywords | string[] | Profile keywords to exclude. |
| companyKeywords | string[] | What the EMPLOYER does, in its own words: each value is a phrase whose words must all appear in the company’s description, specialties, tags or name — or an exact industry label, which then matches every company filed under it; several values OR together. The broad way to ask for "people at cybersecurity companies": an industry label alone misses most of them — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| hqCountry | enum[] | Company headquarters country, ISO 3166-1 alpha-2. |
| hqCity | string[] | Company headquarters city keywords — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| hqState | string[] | Company headquarters state or region — a US state, Canadian province, Australian state or German Land also matches its other spellings ("TX" finds "Texas", "Bayern" finds "Bavaria"), at companies in that country only; add hqCountry to pin an ambiguous code such as WA — matched through the employer: applies when the matching companies (after the HQ, size, industry and company-type filters) number 50,000 or fewer, otherwise named in unsupportedFilters. |
| hqContinent | enum[] | Continent of the company headquarters. |
| hqSalesRegion | enum[] | Commercial region of the company headquarters. |
| technologies | string[] | Technologies detected on the company website (LeadOcean data only). |
| technologyCategories | enum[] | What the detected technology is for, e.g. Analytics or CDN, rather than its name (own data only; covers the ~7.8M crawled companies). |
| emailStatus | enum[] | Email deliverability (LeadOcean data only). |
| emailType | enum[] | Work or personal email (LeadOcean data only). Pair with emailStatus to ask for a deliverable WORK address. |
| hasEmail | boolean | true = only people with a known email, false = only those without (LeadOcean data only). |
| hasPhone | boolean | Only people with, or without, a known phone number (own data only). |
| reachable | enum | Holding an email OR a phone — `strict` additionally requires the email to be verified, catch_all_valid or catch_all. |
| limit | int | Rows to export — the account is charged up to this many records (times 2 when a column needs an enrichment). At most 50,000 per export; 500,000 per day and 10,000,000 per period per account. Call leadocean_count_leads first to size it. |
| columns | string[] | Column ids from GET /v1/exports/columns (the catalogue), in order. Omit to use a preset. Every row costs one record whatever the columns; email_N_* columns need reveal email, phone_N_* need email_phone (enrich scope). |
| preset | string | A named column set instead of listing columns. full (default, 45 columns): identity, profile, address, contact flags, emails 1–3, phones 1–2, current role, education, skills — needs the enrich scope. search (27 columns): what the search row carries, no contact points. One record per row either way. |
| reveal | string | Whether contact points are exported. Derived from the columns when omitted. Needs a key with the enrich scope. |
| name | string | A label for the export, shown in the list and the ready email. |
leadocean_get_export · Get an export (poll) · freeStatus and progress of one export. FREE. While queued or running, wait pollAfter seconds and call again. When done, downloadUrl is a signed link to the plain .csv that opens in a browser WITHOUT an API key — the same link as the ready email — valid until downloadExpiresAt (24 hours, never past the file’s 7 days), and downloadNote says so in a sentence you can pass on. An expired link is renewed by calling this tool again: a new 24-hour link, free, nothing rebuilt, for as long as the file is kept. Give it to the user rather than fetching it here. failed and cancelled exports keep what they wrote: rows written are billed and the partial file is downloadable.
| Input | Type | Meaning |
|---|---|---|
| id | string | The export id from leadocean_export_leads. |
leadocean_get_account · Account status · freeEverything about the account this key spends, in one FREE call: plan and whether it is fair use, records used / remaining / when they reset and what happens past the ceiling (throttled or refused), an active grant, the subscription state (no invoices or card details), today’s and this period’s export rows against their ceilings, and the rate. Call this before a large job, or after a 402 or 429, instead of guessing.
leadocean_list_exports · List exports · freeThe account’s newest exports (up to 100), 90 days of history. FREE. The REST list (GET /v1/exports) pages further with a cursor.
| Input | Type | Meaning |
|---|---|---|
| status | string | Only exports in this state. |
| limit | int | How many of the newest to return, default 25. |
leadocean_mark_viewed · Mark people viewed · freeRemember people as already shown, in a named list kept on the account (not the key). FREE. Then pass excludeViewed: true (and viewedSet) to leadocean_search_leads, count_leads or export_leads to leave them out. Marking twice is harmless. The account holds at most Free 10,000, Solo 100,000, Agency 1,000,000 or Platform 50,000,000 people across all lists.
| Input | Type | Meaning |
|---|---|---|
| ids | string[] | person_ids to remember as shown (each row’s person_id), up to 10,000 per call. |
| set | string | Which list, e.g. one per end client or workspace; default "default". |
leadocean_clear_viewed · Clear viewed people · freeForget people in a viewed list so they can appear again. FREE. With ids, forgets those. Without ids it clears the whole list, in two steps: the first call only reports how many would be removed; repeat with confirm: true to do it.
| Input | Type | Meaning |
|---|---|---|
| ids | string[] | person_ids to forget; omit to clear the whole list. |
| set | string | Which list; default "default". |
| confirm | boolean | Required to clear a WHOLE list: call once without it to see how many would be removed, then again with confirm: true. |
What each tool costs is the same as the REST call behind it — see records, limits and errors. So are its limits: a tool that pages with a cursor stops at the same depth cap as the endpoint underneath it.
The whole API is published as plain Markdown for models: llms.txt is the index and llms-full.txt has every endpoint, parameter, enum value, schema field group, error and tool. Both are generated from the running API, so they never drift. Paste the URL into Claude, add it to Cursor as a doc, or fetch it in your own system prompt.