account_usage
ChatGPTLusha: returns account credit balance, rate-limit status, plan info, and per-action credit pricing. Use when: quoting what an action costs, or checking credit balance and rate-limit headroom before spending. Do not use when: looking up filter values (talent_search_filters, employer_search_filters cover those). Returns: credit balance, rate-limit status (minute/hourly/daily), the current plan, and a pricing map keyed by billable action. Each entry carries the rate, the quantity it covers, and a tools array naming the tools on this surface that charge it. The keys are action names carried over from the wider Lusha API rather than tool names, so read the tools array rather than matching a key to a tool. An empty tools array means the account is charged that rate elsewhere in Lusha, not here. Credits: does not consume credits.
candidate_change_filters
ChatGPTLusha: returns the candidate-level change signal types this account can request. Use when: resolving which candidate change signals exist before requesting them. Do not use when: fetching the changes themselves (candidate_changes returns them). The vocabulary belongs to the signals platform and grows without notice, so a remembered list goes stale silently; a failed call leaves the types unresolved rather than absent. Returns: the supported candidate change signal identifiers (today promotion, companyChange, allSignals). Credits: does not consume credits. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
candidate_changes
ChatGPTLusha: reports whether 1-25 named candidates were promoted or moved. Use when: refreshing a saved talent pipeline, or answering whether anyone has moved. Do not use when: events at an employer (employer_events); finding new candidates (talent_search). Prerequisite: the available change types are returned by candidate_change_filters. Each entry: caller 'id' plus LinkedIn URL, email, or name and employer. Defaults: 6 months, 10 per type. Returns: results[] per caller id with dated change events (or NOT_FOUND), the window, and billing. Credits: consumes Lusha credits per signal returned. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
candidate_lookup
ChatGPTLusha: looks up 1-25 candidates the recruiter already holds, by Lusha id, name plus employer, LinkedIn URL, or email. Use when: the recruiter names specific people or pastes identifiers they already hold. Do not use when: sourcing by position criteria (talent_search); opening a full profile (candidate_profile). 'enrich' defaults to true, which reveals emails and phones for the whole batch; false returns a preview. Returns: candidate profiles with available business data. Each candidate carries a has array listing which fields the record holds; partialProfile appearing in has means the flag exists, not that the profile is partial, and its value only arrives on candidate_profile. Credits: consumes Lusha credits per candidate resolved, plus reveal credits per email and phone when enrich is true. account_usage carries the rates for this account and names this tool on each one it charges. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
candidate_profile
ChatGPTLusha: opens the full profile for named candidates, adding job start date, previous employment and LinkedIn counts. Use when: the recruiter picked specific candidates and wants their profile or a way to reach them. Do not use when: finding candidates (talent_search); refreshing a saved pipeline (list_read, candidate_changes). Omitting 'reveal' reveals every available field, phone included. Returns: revealed emails/phones (dataSource: lusha or third-party vendor), missingDataPoints[], request status, and non-billable profile fields. previousEmployment is populated for most candidates and genuinely empty for some; an empty array means no history is held, not that the candidate has none. jobTitle.seniority comes back capitalised here and lower-cased from talent_search, so normalise case before comparing the two. Credits: consumes Lusha credits per candidate; phone costs more than email. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
candidate_profile_runs
ChatGPTLusha: lists the account's recent background candidate-profile reveals, newest first. Use when: a background reveal was started earlier and its job id is no longer to hand. Do not use when: the job id is known (candidate_profile_status reports one reveal directly), or no candidate_profile response has carried a job block in this session. Takes no arguments and reports scalars only; jobs[].jobId feeds candidate_profile_status and candidate_profile_results. An account with nothing running returns an empty jobs array rather than an error. Reveals stay listed for about 3 hours after the candidate_profile request that created them, ordered by most recent activity. Returns: requestId, jobCount, activeJobCount and jobs[] with jobId, status, requestId, createdAt, expiresAt, contactCount and outstandingCount. No candidate data. Credits: does not consume credits.
candidate_profile_status
ChatGPTLusha: returns progress counts for a background candidate-profile reveal, with no candidate data. Use when: a prior candidate_profile response carried a job block and the question is whether its outstanding reveals have landed yet. Do not use when: the revealed candidates themselves are wanted (candidate_profile_results returns them), or the candidate_profile response carried no job block, which makes it already final. Prerequisite: a job id from the job.id field of a candidate_profile or candidate_lookup response. isTerminal false with pollAgainInSeconds set describes a reveal still running; isTerminal true means the data is final and later reads return the same body. pollsRemainingBeforeExpiry counts the reads that fit before the nominal 3-hour expiry at the returned cadence; 0 alongside isTerminal false describes a reveal past that window whose store lease keeps sliding, so one more read can still succeed. creditsCharged is the running total for the whole candidate_profile request, immediate reveals included, rather than a background-only increment. Returns: jobId, requestId, status, isTerminal, pollAgainInSeconds, secondsUntilExpiry, pollsRemainingBeforeExpiry, pastExpiry, contactCount, contactsWithOutstanding, outstandingCount, outstandingByType, resolvedCount, notFoundCount, coversRemaining and creditsCharged. No emails, phones or profile data. Credits: does not consume credits.
employer_event_filters
ChatGPTLusha: discovers the employer signal types and the filter directory, or the values of one filter type. Use when: resolving employer signal or news event types before requesting employer events. Do not use when: candidate-level change types (candidate_change_filters); the events themselves (employer_events). Omit filterType for the directory and set it for values. 'hiringByLocations' requires 'query'. Returns: Directory: { signalTypes, availableFilters }. Values: { filterType, values }. Credits: does not consume credits. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
employer_events
ChatGPTLusha: returns dated events at 1-25 named employers. Use when: establishing why now, sourcing from employers in contraction, or checking what changed at an employer. Do not use when: finding employers (employer_search); a candidate's own move or promotion (candidate_changes). Prerequisite: valid signal and news event types are returned by employer_event_filters. Each entry: caller 'id' plus name or domain. Defaults: 6 months, 10 per type. Returns: results[] per caller id with dated events, or an error code (NO_SIGNALS_FOUND / NOT_FOUND), plus the date window and billing. An entry with no signals carries the resolved id and the error only, with no companyName, so a genuinely quiet employer and a wrongly resolved entity cannot be told apart. eventSummary is generated from the article text and can misstate the person's role and employer: one returned "Andrea D'Amico leaves Booking.com Limited as CEO" for someone who was never Booking's CEO. Read articleTitle and articleHighlight and describe the event from those. The same event can arrive under several signalIds with conflicting eventEffectiveDates, so dedupe by person and prefer the most recently published article. Credits: consumes Lusha credits twice: on the employers it resolves, then on each signal returned. An employer that returns nothing still costs its share of the resolution. maxResultsPerSignal bounds the signals per employer, so employers x maxResultsPerSignal bounds the larger half. account_usage carries both rates for this account and billing.creditsCharged the actual charge. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
employer_lookup
ChatGPTLusha: looks up 1-25 named employers by name, domain or FQDN. Use when: the recruiter names an employer, or a shortlist needs employer detail. Do not use when: finding employers by criteria (employer_search); recent events at one (employer_events). Optional 'enrich' bundles reveal fields; false returns a preview only. Returns: employer profiles with available firmographic data. Credits: consumes Lusha credits per successful lookup, plus reveal credits when enrich is true. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
employer_search
ChatGPTLusha: filters are flat top-level fields; only exclude groups other filters (exclude.companies), and object-valued fields such as signals keep their own schema. Finds employers to source talent from, by industry, size, location or technology; requires at least one filter. Use when: building a set of employers to source from before sourcing the people inside them. Do not use when: a named employer (employer_lookup); events at one (employer_events). Prerequisite: valid filter values are returned by employer_search_filters. Example: {"locations": [{"country": "United States"}], "keywords": ["fintech"], "exclude": {"companies": {"domains": ["acme.com"]}}}. There is no include or filters wrapper; an unrecognized top-level key returns an error that restates this shape and, for a filter nested under a wrapper, names its flat field; nothing is searched or charged. An empty array means no filter on that field. Accepts a signals filter, which narrows to employers with a hiring surge or contraction. Returns: paginated employers. Credits: may consume Lusha credits per request. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
employer_search_filters
ChatGPTLusha: resolves the valid employer filter values employer_search accepts, one filter type per call. Use when: resolving industry, size, location or technology wording into valid values. Do not use when: a named employer (employer_lookup); candidate-side criteria (talent_search_filters). Filter types names, locations and technologies require the "q" parameter, which also narrows them. Other types ignore "q": enumerable types return a fixed list, free-text types an empty one. Credits: does not consume credits. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_add_candidates
ChatGPTLusha Workspace: adds known Lusha candidate ids to a talent pipeline; duplicates are deduped. Use when: saving named candidates or a shortlist onto an existing pipeline. Do not use when: creating the pipeline (list_create); taking candidates off it (list_remove_candidates). The search tools also accept a pipeline id directly, which writes their results in the same call. Returns: the added row count and the pipeline id. Credits: free on a candidate pipeline. On a pipeline of employers, consumes Lusha credits per newly added employer. Credits for every employer sent are reserved before the add, so a balance that cannot cover them fails with HTTP 402 and adds nothing; duplicates and invalid ids are not charged. billing.creditsCharged reports the actual charge. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_add_columns
ChatGPTLusha Workspace: adds one or more Lusha catalog columns to a talent pipeline and populates them across its rows. Use when: a recruiter wants Lusha data points on a pipeline, one or several in a single call. Do not use when: refreshing a column already on the pipeline (list_run_column); removing one (list_remove_column). Prerequisite: the column keys come from list_available_columns; the pipeline id from list_create or list_find. A Lusha column is filled over the whole pipeline, so adding one starts its run and there is no add-without-run; progress is read from list_run_status. Outcomes come back per column in request order, so one column failing leaves the others added. Lusha catalog columns only: crm, ai, tracking and score columns are not addable through the public API. Returns: per-column status (added/failed) with columnId and name, plus added/failed totals. Credits: consumes Lusha credits per billable row the added columns populate. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_available_columns
ChatGPTLusha Workspace: lists every Lusha data column available to add to a talent pipeline. Use when: choosing which data points to enrich a pipeline with, or resolving one to the columnKey that list_add_columns takes. Do not use when: the columns a pipeline already holds (list_columns); the candidate rows themselves (list_read). The catalog is fixed per entity type and independent of any pipeline, so it answers what a pipeline could hold rather than what it does. Returns: catalog entries (category, displayName, columnKey, type) for the entity type. Credits: does not consume credits. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_columns
ChatGPTLusha Workspace: lists a talent pipeline's columns with per-status row counts. Use when: discovering the columns a pipeline already has, and their column id, before running or removing one. Do not use when: the columns available to add (list_available_columns); the candidate rows (list_read); run progress totals (list_run_status). Returns: columns (columnId, name, type, key, isDefault, timestamps) with per-status row counts. Credits: does not consume credits. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_create
ChatGPTLusha Workspace: creates an empty talent pipeline in the recruiter's workspace to collect saved candidates. Use when: saving a shortlist so it can be worked in later sessions. Do not use when: a pipeline already exists (list_find resolves a name to its id); adding candidates (list_add_candidates). Set entity_type to 'contacts' for a candidate pipeline; it cannot be changed later. Ownership resolves from the signed-in caller. Returns: the created pipeline (id, name, entityType, visibility, owner, timestamps). Credits: no reveal credits. Write cost is not yet measured. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_find
ChatGPTLusha Workspace: lists the caller's talent pipelines with pagination and name or status filters. Use when: discovering existing pipelines, or resolving a pipeline name to its id before reading it. Do not use when: reading the candidates on one (list_read); run progress (list_run_status). Ownership resolves from the signed-in caller, so the pipeline name is the only filter needed. Returns: paginated pipelines (id, name, entityType, visibility, status, owner, timestamps). Credits: free; verified at 0 charged across 16 pipelines. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_read
ChatGPTLusha Workspace: reads a page of a talent pipeline, including populated column values. Use when: retrieving the candidates saved on a pipeline, for example before checking what changed. Do not use when: aggregate counts and run progress (list_run_status); listing columns (list_columns). Candidate values come back masked, and the cost is charged on rows returned rather than on anything revealed, so paging keeps it proportional. Returns: a page of candidate rows (candidate data plus column values) and pagination. Credits: consumes Lusha credits on rows returned, revealed or not. account_usage carries the rate and the number of rows it covers for this account. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_remove_candidates
ChatGPTLusha Workspace: removes candidates, by Lusha id, from a talent pipeline. Use when: the recruiter asked for specific named candidates to come off a pipeline. Do not use when: archiving the whole pipeline (list_update); removing a column (list_remove_column). The API offers no undo, so the removal is final once it returns. Returns: the removed row count and the pipeline id. Credits: does not consume credits. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_remove_column
ChatGPTLusha Workspace: removes a non-default column from a talent pipeline. Use when: a column the recruiter asked to drop is no longer needed. Do not use when: removing candidates (list_remove_candidates); emptying a column without dropping it. Values already populated in the column are lost with it. Returns: the removed column id. Credits: does not consume credits. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_run_column
ChatGPTLusha Workspace: populates a column across all rows, missing rows only, or specific rows. Use when: populating or refreshing a column for candidates already on a pipeline. Do not use when: creating the column (list_add_columns); reading results (list_read, list_run_status). A reveal-type column charges per row, so one call on a 500-row pipeline spends at pipeline scale: the only call here that does. Runs are async. Returns: the column id, the run scope, and the async run status. Credits: consumes Lusha credits per billable row the run populates. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_run_status
ChatGPTLusha Workspace: returns one talent pipeline's candidate count and per-column run totals. Use when: polling progress after a column run, or checking whether a pipeline is still processing. Do not use when: browsing pipelines (list_find); reading candidate rows (list_read). A partially completed run reports which rows populated, so a re-run can be scoped to the rest instead of repeating the whole column. Returns: pipeline metadata plus entityCount, isProcessing, and per-column rowsNotRun/Processing/Success/NoData/Failed. Credits: does not consume credits. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
list_update
ChatGPTLusha Workspace: renames a talent pipeline, changes its visibility, or archives and unarchives it. Use when: renaming a pipeline, sharing it, or archiving it. Do not use when: changing who is on it (list_add_candidates, list_remove_candidates); its columns (list_add_columns). Metadata only; the candidates on the pipeline are untouched. This server exposes no tool that deletes a pipeline, which stays in the Lusha UI. Returns: the updated pipeline record. Credits: no reveal credits. Write cost is not yet measured. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
report_event
ChatGPTReports a client-side BI event.
similar_candidates
ChatGPTLusha: widens a shortlist with candidates resembling 5-100 seed candidates. Use when: a shortlist is too short and the recruiter wants more of the same shape. Do not use when: clear criteria were given (talent_search filters are more precise); fewer than 5 seeds exist. Precision measured around 70% on test, drifting into unrelated senior profiles. Re-use dedupeSessionId for follow-up pages; it expires after 30 days. Returns: candidates similar to the seeds, plus dedupeSessionId, meta.hasMore and credits. Each candidate carries a has array listing which fields the record holds; partialProfile appearing in has means the flag exists, not that the profile is partial, and its value only arrives on candidate_profile. Credits: consumes Lusha credits per request. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
similar_employers
ChatGPTLusha: finds employers similar to 5-100 seed employers. Use when: a profile sources well from one employer and the recruiter wants comparable ones. Do not use when: a named employer (employer_lookup); filtering by criteria (employer_search). Re-use dedupeSessionId for follow-up pages; it expires after 30 days. Returns: similar employers (employees, industry, location), dedupeSessionId, meta.hasMore and credits. Credits: consumes Lusha credits per request. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
talent_search
ChatGPTLusha talent sourcing: finds candidates in the talent pool by position criteria. Requires one filter. Use when: sourcing candidates for an open position or from a job description. Do not use when: a candidate is already named (candidate_lookup); saved candidates moved (candidate_changes). Prerequisite: valid filter values are returned by talent_search_filters. Tenure is expressed through the job-change date bounds; the exclude parameter explains how. Returns: paginated candidates (title, employer, location, LinkedIn); nothing revealed. The same candidate id can appear twice in one page under two employers, typically a consultancy and the client they sit at, so dedupe on id before counting or presenting. Each candidate carries a has array listing which fields the record holds; partialProfile appearing in has means the flag exists, not that the profile is partial, and its value only arrives on candidate_profile. Credits: may consume Lusha credits per request. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
talent_search_filters
ChatGPTLusha talent sourcing: resolves recruiter wording into the exact values talent_search accepts, one filter type per call. Use when: mapping level, department, location, title or certification phrasing to valid filter values. Do not use when: sourcing candidates (talent_search); employer criteria (employer_search_filters). Certification vocabulary is unnormalised, so one qualification returns several spellings and all of them narrow differently, and most of what comes back is not a certification. The response caps at 100 values per query, so an unfiltered lookup is already hiding spellings. Filter to values containing 'Certified' before passing them to talent_search. Type 'skills' returns an empty list. Returns: the valid values for the requested filter type. Credits: does not consume credits. Rate limits apply per Lusha plan (per-minute/hourly/daily); exceeding returns HTTP 429. The account_usage tool returns current limits and remaining headroom.
