Search search
Kenso Search: 280M people and companies, plus bulk pause, resume, restore and update of many workspace contacts (contacts-bulk-*). search-* and get-*-facets take one body object; its filter keys are in load_skill('ken-search'). When the request names the values, call search-people or search-companies with them directly: no facets, expand or get-filters first. When it asks which values exist (industry taxonomy names, with counts): get-people-facets. expand only suggests similar titles or industries with AI. Skip get-filters (the whole dropdown catalog, 20-50k tokens). A LinkedIn URL: search(operation="lookup-person", linked_in_url=...), or lookup-company. A company's tech stack, brand and funding by domain: saved_searches company-data-get.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through search_read and changes through search_write. Each takes operation plus that operation's parameters, and your workspace role decides which operations you see.
Each operation with a route calls the Kenso API at https://api.ken.so with Authorization: Bearer <Kenso API key>, Ken-Version: 1.1 and X-Ken-Workspace-Id: <workspace id>. You can call that route directly with the same headers.
Operations: contacts-bulk-pause, contacts-bulk-restore, contacts-bulk-resume, contacts-bulk-update, expand, get-company, get-company-facets, get-filters, get-people-facets, get-person, get-place, headcount_changes, lookup-company, lookup-person, search-companies, people_in_accounts, search-people, search-places, enrich, job_changes
contacts-bulk-pause
Write. POST https://api.ken.so/v1/contacts/bulk-pause
Body (json): ids array
Pause the campaign sequence of up to 1,000 contacts by id. Not do-not-contact. Pending unsent steps are cancelled. Resume with contacts-bulk-resume.
POST /api/v1/contacts/bulk-pause. Public. Sends Ken-Version 1.1.
Requires campaigns edit and the launch feature, and the pause_leads
feature flag (404 while it is off).
Each contact is one lead in one campaign; the pause stops that campaign's
sequence only and sets sequenceStoppedAt and sequenceStopReason "paused" on
the contact. data.succeeded lists the ids paused after the call, leads that
were already paused included, so a retry is safe. data.failed lists
{ id, error: { code, message } } with code already_stopped (another stop
reason holds it), do_not_contact, not_found (not in this workspace, deleted,
or not in a campaign), or internal_error (retry that id). 200 even when
some fail.
contacts-bulk-restore
Write. POST https://api.ken.so/v1/contacts/bulk-restore
Body (json): ids array
Restore up to 1,000 soft-deleted contacts by id, the undo of contacts-bulk-delete. Each contact goes back into the campaign and segment it was deleted from.
POST /api/v1/contacts/bulk-restore. Public. Sends Ken-Version 1.1.
Requires campaigns edit, matching bulk-delete.
The contact keeps its campaign, segment, emails and fields. Nothing is
charged and no enrichment re-runs. A restored contact is live again, so an
active campaign can schedule its next email steps to it. LinkedIn steps
stopped while it was deleted stay stopped. Any soft-deleted contact comes
back, including a lead the end client removed in a lead-list approval, and
that approval is not updated. data.restored counts the
ids restored (data.succeeded lists them). data.failed lists
{ id, error: { code, message } } with code not_deleted (the contact is live,
nothing changed; data.skipped counts these), not_found (missing or not in
this workspace) or internal_error (retry that id). 200 even when some fail.
A retry is safe: an id an earlier call already restored comes back
not_deleted.
contacts-bulk-resume
Write. POST https://api.ken.so/v1/contacts/bulk-resume
Body (json): ids array
Resume the campaign sequence of up to 1,000 paused contacts by id. Only a "paused" stop is cleared; other stop reasons stay.
POST /api/v1/contacts/bulk-resume. Public. Sends Ken-Version 1.1.
Requires campaigns edit and the launch feature. Not behind the pause_leads
flag, so a lead paused before the flag was turned off can still be resumed.
Clears the stop only where sequenceStopReason is "paused", then asks the
planner to plan each affected campaign now. A held LinkedIn step picks up
within the hour. data.succeeded lists the ids
resumed. data.failed lists { id, error: { code, message } } with code
not_paused (no stop, or a stop with another reason such as account_play,
which stays) or not_found. 200 even when some fail.
contacts-bulk-update
Write. POST https://api.ken.so/v1/contacts/bulk-update
Body (json): items array
Update up to 1,000 contacts in one call. Prefer this over api_contacts_update in a loop. Each item is a contactId plus the fields api_contacts_update accepts.
POST /api/v1/contacts/bulk-update. Public. Sends Ken-Version 1.1.
Requires Campaigns edit. Prefer this over calling contacts(operation="update") in a loop:
it counts as one bulk request against the workspace rate limit.
items: 1 to 1,000 objects, each { "contactId": int, ...fields }. Fields are
firstName, lastName, title, linkedInUrl, location, email (strings, null clears),
isQualified (a verdict set by hand that AI qualification never re-decides
until an AI flow reset, as on the single update; boolean, null rejected) and
doNotContact (boolean, null rejected), outreachLanguage (a
locale such as fr-FR; sets it by hand and locks it, null clears and unlocks it),
customVariables (an object of key -> string, number, boolean or null that
merges as on the single update: a string sets a key, null or "" removes it,
and a number or boolean is sent as text the same way), and customImageUrl
(the https URL of the lead's own image, shown in emails as {{custom_image}};
Kenso downloads and hosts it, an empty string or null clears it, and it needs
campaign images on the workspace), and customVideo (the lead's own video, a
Loom, YouTube, Vimeo, Wistia, Vidyard, Sendspark or HeyGen share link or
embed code, shown in emails as {{custom_video}}; an empty string or null
clears it, and it needs campaign videos on the workspace and a contact in a
campaign). snake_case names work too (outreach_language, custom_variables,
custom_image_url, custom_video).
Absent fields stay unchanged. contactId must be unique within the call.
Each item reports its own result in data.results (request order) with status
updated, not_found, validation_failed, video_in_use (the lead's video is
used by a sent or queued step, so it cannot change and the old one stays),
or failed (anything else, a lost race on the video included; retry it), and
an error message when it did not update. data.updated and
data.failed count them. One bad item does
not stop the others. A malformed items list is a 400 and nothing is written.
expand
Read. POST https://api.ken.so/v1/search/people/expand-titles
Expand job titles or industries into similar/related values using AI.
Expand filter values into similar/related alternatives using AI. Useful for
broadening searches to capture synonyms and related sectors.
Each expansion is a Kenso-paid model call. The same list in the same workspace
comes back from the last hour's answer at no cost. Anything else takes one
unit of the workspace's aiSearchExpand quota (20 a minute, 500 a day, shared
by both kinds): past it, 429 quota_exceeded with Retry-After. Expand once per
filter set rather than per value.
### kind=titles
Expand job titles into similar/related titles using AI.
Send a list of titles and get back expanded alternatives for each.
Useful for broadening title-based searches to capture variations
and synonyms (e.g., "CEO" -> ["CEO", "Chief Executive Officer", ...]).
Args:
client_id: Optional workspace id, sent as X-Ken-Workspace-Id. Staff and
multi-workspace callers pass it to pick the workspace.
titles: List of job titles to expand (e.g., ["CEO", "CTO"]) - required
Returns:
expandedTitles: dict mapping each input title to a list of
related/similar titles
Endpoint: POST /v1/search/people/expand-titles (search.expand-titles)
### kind=industries
Expand industries into similar/related industries using AI.
Send a list of industries and get back expanded alternatives for each.
Useful for broadening industry-based searches to capture variations
and related sectors (e.g., 'Software' -> ['Software', 'SaaS', 'IT Services', ...]).
Max 50 industries per call.
Args:
industries: List of industry names to expand - required
Returns:
expandedIndustries: dict mapping each input industry to a list of
related/similar industries
Endpoint: POST /v1/search/metadata/expand-industries (search.expand-industries)
Both routes are public and take Ken-Version 1.1.
get-company
Read. GET https://api.ken.so/v1/search/companies/{companyId}
Path: companyId
Get one company from the accounts index. Public. company_id is the index id.
GET /api/v1/search/companies/{companyId}. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
company_id is a search-companies row's kenId. Returns the full record.
get-company-facets
Read. POST https://api.ken.so/v1/search/companies/facets
Facet counts for a company search. Public. The path is companies and the index is accounts.
POST /api/v1/search/companies/facets. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. The body takes the same technology keys as company search: webTechAny, webTechAll, webTechExclude and webTechCategories. Values are technology keys and category keys from saved_searches(operation="list-web-technologies"). Exclude only matches companies with at least one detected technology. The facets carry webTech (the top 50 technologies, each bucket with a label) and webTechCategories (the top 30 categories). While the feature is off in Search, the call fails with 400 validation_failed, "Technology filters are not enabled." (Search's web_tech_filters_disabled) and the facets carry neither. The body also takes lookalike as company search does, behind the same lookalikes feature (403 feature_disabled while it is off), so the counts match a lookalike search. It takes inLinkedInConnections as company search does.
get-filters
Read. GET https://api.ken.so/v1/search/filters
List search filters. This replaces metadata filters. Public. The index is global.
GET /api/v1/search/filters. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. The workspace header admits the caller and is not forwarded.
get-people-facets
Read. POST https://api.ken.so/v1/search/people/facets
Facet counts for a people search. Public. body is the same search object as people search.
POST /api/v1/search/people/facets. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. The body takes the same company technology keys as people search: companyWebTechAny, companyWebTechAll, companyWebTechExclude and companyWebTechCategories. Values are technology keys and category keys from saved_searches(operation="list-web-technologies"). Exclude only matches companies with at least one detected technology. While the feature is off in Search, the call fails with 400 validation_failed, "Technology filters are not enabled." (Search's web_tech_filters_disabled). The body also takes companyLookalike and lookalike as people search does, behind the same lookalikes feature (403 feature_disabled while it is off), so the counts match a lookalike search. It takes inLinkedInConnections as people search does.
get-person
Read. GET https://api.ken.so/v1/search/people/{personId}
Path: personId
Get one person from the global index, with the full record. Public. person_id is the index id.
GET /api/v1/search/people/{personId}. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
person_id is a search-people row's kenId. Returns the whole profile:
work history, education, skills, summary and activity, which search rows leave out.
The person carries hasKenEmail and kenEmailStatus, as in search-people.
get-place
Write. Early access: needs search_places on for the workspace. GET https://api.ken.so/v1/search/places/{placeId}
Path: placeId
Open one Google Maps place with its details. An open: free up to 500 opens a day per workspace, then 0.1 credits.
GET /api/v1/search/places/{placeId}. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
place_id is a plc_ id from search-places; a place this workspace has not seen is not_found.
Returns data.place (the search fields), data.details (websiteUrl, plusCode, ratingCounts,
attributes, description; null when Google has none) and data.charge. Cost: free up to 500
opens a workspace a UTC day (a place, its reviews and its photos all count), then 0.1
credits (100 millicredits) an open; the same open again the same day costs nothing.
headcount_changes
Read. GET https://api.ken.so/v1/search/headcount-changes
Query: cursor string, limit integer, minGrowthPct number, month string
List detected month-over-month company headcount increases from Kenso Search.
List detected month-over-month company headcount increases from Kenso Search.
This is the internal headcount-growth signal feed consumed by backend trigger
sweeps. Use it to page through companies whose Kenso Search employee count grew
between ingestion snapshots.
Args:
client_id: Optional workspace id, sent as X-Ken-Workspace-Id. Staff and
multi-workspace callers pass it to pick the workspace.
month: Detection month in yyyy-MM format. Omit to return all months, most recent first.
min_growth_pct: Minimum growth percentage threshold, e.g. 10.0 for at least 10% growth.
page: Page number (default: 1). Pages after the first walk the earlier
ones, so prefer cursor past page 3.
page_size: Results per page (default: 100, max: 100)
cursor: pagination.nextCursor from the previous result. Replaces page.
Returns:
page, pageSize, hasMore, and results with company IDs, name, domain,
LinkedIn URL, previous/current employee counts, absolute growth, growthPct,
detectedMonth, and detectedAt, plus a top-level pagination
{ nextCursor, hasMore }. The Kenso API does not return a total count.
Endpoint: GET /v1/search/headcount-changes
lookup-company
Read. GET https://api.ken.so/v1/search/companies/lookup
Query: linkedInUrl string
Look up one company by LinkedIn URL. Public. linked_in_url is required.
GET /api/v1/search/companies/lookup. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Query key linkedInUrl. The API reads the accounts index.
lookup-person
Read. GET https://api.ken.so/v1/search/people/lookup
Query: linkedInUrl string
Look up one person by LinkedIn URL. Public. linked_in_url is required.
GET /api/v1/search/people/lookup. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Query key linkedInUrl. The workspace header is not forwarded. Returns the full record, like get-person. The person carries hasKenEmail and kenEmailStatus, as in search-people.
search-companies
Read. POST https://api.ken.so/v1/search/companies
Search companies. The path is companies and the index is accounts. Public. A 2xx body is success and data. Rows are compact; get-company has the full record.
POST /api/v1/search/companies. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
The API forwards this body to the accounts index.
Each row in data.results is compact: kenId, name, domain, website,
linkedInUrl, industry, type, size, employeesCount, founded, description (cut to
300 characters, ending in "..."), the headquarters fields, the funding fields, and
the signals (headcount growth and decline, crossedSizeBandUp, enteredSizeBand,
leadershipChanges, hiringSurges). A key with no value is left out. Locations,
specialties, funding rounds and similar companies are not in the rows: call
search(operation="get-company", company_id=<kenId>) or
search(operation="lookup-company", linked_in_url=...) for the full record.
fundingAmount {min, max} and raisedFundingRecently with raisedFundingWithinDays
(1-3650) use Kenso's merged funding data: the larger of the profile's total funding and
the funding rounds Kenso tracks, and the later last funding date. Each company carries
fundingTotalUsd and lastFundedAt (yyyy-MM-dd), null when unknown.
Technology keys (the technologies Kenso found for the company's domain: its website's pages,
its DNS records and its job posts): webTechAny (the company runs at least one of the keys),
webTechAll (all of them), webTechExclude (none of them) and webTechCategories (any
technology in one of the category keys). Values are
technology keys and category keys from saved_searches(operation="list-web-technologies"). Exclude
only matches companies with at least one detected technology, so a company Kenso has not
scanned is never "without" a technology. While the feature is off in Search, the call fails with 400 validation_failed, "Technology filters are not enabled." (Search's web_tech_filters_disabled).
Each company carries webTechnologies [{key, name, categories}], null when the feature is off or none was detected.
body.inLinkedInConnections: true keeps only companies where a workspace LinkedIn connection
works or worked. Needs linkedin_network or linkedin_connections_import (else 403).
Lookalike filter (the workspace's lookalikes flag): lookalike finds companies like the seeds.
{seeds: 1-100, each with exactly one of companyId (a kenId), domain, linkedInUrl or text
(what the company does, up to 4,000 characters); negatives: 0-100 companies to steer away
from (companyId, domain or linkedInUrl, no text); mode: precise (default, the same products)
or broad (the same industries, wider); minGrade: a whole number 1-5 (default 2; 3 keeps a
tight list; precise mode drops rows graded below it, broad keeps every row);
excludeDomains: 0-10,000 domains to leave out (the backend already leaves out the workspace's
blocklist and customers); includeNonB2b: default false}. The other keys still filter.
Example: search(operation="search-companies", body={"lookalike": {"seeds": [{"domain":
"acme.com"}, {"domain": "northwind.io"}], "mode": "precise", "minGrade": 3},
"countries": ["United States"], "pageSize": 25}).
Seeds from the workspace's customers, CRM deals, Interested replies, any replies, a campaign's leads or website
visitors: crm(operation="list-lookalike-seeds", source="customers").
With it, rows sort by similarity (sortBy is ignored), at most 2,000 are reachable through
the usual paging (send a returned searchAfter back unchanged), each row carries lookalike
{score 0-100, grade 1-5, 5 best}, and data carries lookalikeSeeds {resolved [{input,
companyId, personId, name, domain}], unresolved [{input, reason}]} (reason not_found,
no_text, embedding_unavailable or not_b2b_excluded). Errors: 403 feature_disabled (no
lookalikes flag), 400 lookalikes_unavailable (not switched on yet), 400 too_many_seeds,
400 invalid_lookalike (malformed filter, or a minGrade that is not a whole number 1-5), 422 no_usable_seeds (no seed resolved; the error carries lookalikeSeeds). Lookalike
results are a snapshot: a saved search, search import, saved-list source or approval
filter that carries lookalike is refused with 400 lookalike_not_storable, so keep the
returned companies as a selection (their kenIds into
search(operation="people_in_accounts", account_ids=[...]), their domains into a saved
list or accounts).
people_in_accounts
Read. POST https://api.ken.so/v1/search/companies/people
Search for people within specific companies/accounts.
Search for people within specific companies/accounts.
First search for accounts, then use their IDs to find people at those companies.
Each person carries hasKenEmail: true when Kenso already holds a recently
verified email for that LinkedIn profile (free on a paid plan when imported).
It also carries kenEmailStatus (none, risky, catch_all or verified), a label only.
Args:
account_ids: List of Kenso company IDs (required)
current_titles: Title filters
exclude_titles: Titles to exclude
seniority_levels: Seniority filters
functions: Function filters
industries: Industry filters
skills: Skill filters (match ANY, case-insensitive)
exclude_skills: Exclude anyone with ANY of these skills (case-insensitive)
keywords: Keyword search
tenure_ripe: True to find people at or above the role-tenure threshold
tenure_ripe_threshold_years: Minimum years in current role for tenure-ripe; defaults to backend threshold
countries: Country filters
states: State filters
cities: City filters
new_in_seat: True to find people recently new at their current company
new_in_seat_window_days: New-in-seat tenure window in days (30, 60, or 90)
new_in_role: True to find people recently new in their current role
new_in_role_window_days: New-in-role tenure window in days (30, 60, or 90)
client_id: Optional workspace id, sent as X-Ken-Workspace-Id.
page: Page number (default: 1)
page_size: Results per page (default: 25)
search_after: Pagination cursor
sort_by: Sort field (default: "relevance")
sort_order: Sort direction (default: "desc")
Rows are compact, the same fields as search(operation="search-people"); call
search(operation="get-person", person_id=<kenId>) for the full record.
Endpoint: POST /v1/search/companies/people (account_ids is sent as companyIds)
search-people
Read. POST https://api.ken.so/v1/search/people
Query: view string
Search people in the global index. Rows are compact; get-person has the full record. Public. A 2xx body is success and data. The workspace header is not forwarded.
POST /api/v1/search/people. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
body is the search request object, forwarded as JSON.
Each row in data.results is compact, the fields to pick and contact someone:
kenId, fullName, firstName, lastName, headline, linkedInUrl, currentTitle,
seniorityLevel, function, isDecisionMaker, yearsInCurrentRole, yearsInCurrentCompany,
yearsOfExperience, currentCompanyId, currentCompanyName, companyDomain,
companyLinkedInUrl, industry, companySize, employeesCount, companyFundingTotalUsd,
companyLastFundedAt, location, city, state, country, countryIso2, and the signals
changedJobRecently, jobChangeDate,
jobChangeDetectedMonth, previousCompanyName, newInSeat, newInRole, tenureRipe,
titleChangedRecently, titleChangeDetectedMonth, previousTitle, promoted,
seniorityIncreased, previousSeniorityLevel, hasKenEmail, kenEmailStatus,
companyWebTechnologies, searchToken (import it with linkedInUrl) and matchedCurrentRole (the current role that matched
currentTitles when currentTitle does not). A key with no value is left out.
Work history, education, skills, summary and activity are not in the rows: call
search(operation="get-person", person_id=<kenId>) or
search(operation="lookup-person", linked_in_url=...) for the full record.
Company funding keys: companyFundingAmount {min, max} filters on the current
company's total funding raised (whole USD, at least 0, min no greater than max), and
companyFundedWithinDays (1-3650) on its last funding date. Both use Kenso's merged
funding data. Each person carries companyFundingTotalUsd and companyLastFundedAt
(yyyy-MM-dd), null when unknown.
Company technology keys (the technologies Kenso found for the current company's domain: its
website's pages, its DNS records and its job posts): companyWebTechAny (the company runs at
least one of the keys), companyWebTechAll (all of them), companyWebTechExclude (none of them)
and companyWebTechCategories (any technology in one of the category keys). Values are technology keys and category keys from
saved_searches(operation="list-web-technologies"). Exclude only matches companies with at least
one detected technology, so a company Kenso has not scanned is never "without" a technology.
While the feature is off in Search, the call fails with 400 validation_failed, "Technology filters are not enabled." (Search's web_tech_filters_disabled). Each
person carries companyWebTechnologies [{key, name}], null when the feature is off or none was detected.
Each person also carries hasKenEmail: true when Kenso already holds a recently
verified email for that LinkedIn profile. On a paid plan that address costs no
email find when the person is imported; on Free it is still a find.
kenEmailStatus labels the best address Kenso holds for the person: none, risky,
catch_all or verified (verified is exactly hasKenEmail true). It is a label only:
you cannot filter or sort by it, and no address is returned.
With behavior_signals each person also carries behaviorTags (what Kenso learned from
outreach to the person, e.g. cold_responder; network tags with behavior_signals_network;
empty when none). body.behaviorTags (any-match) keeps only people carrying one, after
Search answers: a page can be short of pageSize, and totalResults and hasMore count
before it. Without the feature it is a 400. email_confirmed, email_dead_end and
left_company cannot be filtered.
body.inLinkedInConnections: true keeps only the workspace's 1st-degree LinkedIn
connections. Needs linkedin_network or linkedin_connections_import (else 403).
Count a whole selection before importing with
saved_searches(operation="preview-import", ...).
Lookalike filters (the workspace's lookalikes flag), at most one per request:
- companyLookalike: people at companies like the seed companies. The same object as
search-companies' lookalike: seeds 1-100, each with exactly one of companyId (a
company kenId), domain, linkedInUrl or text (what the company does, up to 4,000
characters); negatives 0-100 (no text); mode, minGrade, excludeDomains, includeNonB2b.
- lookalike: people like the seed people, in the same function and seniority with a
matching title, at companies like theirs. {seeds: 1-50, each with exactly one of
personId (a person kenId) or linkedInUrl; negatives: 0-50; mode: precise (default)
or broad; minGrade: a whole number 1-5 (default 2; 3 keeps a tight list);
includeSeedCompanies: default false, so the seeds' own companies are left out}.
Example: search(operation="search-people", body={"companyLookalike": {"seeds":
[{"domain": "acme.com"}, {"domain": "northwind.io"}], "minGrade": 3},
"currentTitles": ["founder", "ceo"], "pageSize": 25}).
With either, rows sort by similarity (sortBy is ignored), at most 2,000 are reachable
through the usual paging (send a returned searchAfter back unchanged), each row
carries lookalike {score 0-100, grade 1-5, 5 best}, and data carries lookalikeSeeds
{resolved [{input, companyId, personId, name, domain}], unresolved [{input, reason}]}
(reason not_found, no_text, embedding_unavailable or not_b2b_excluded). Errors: 403
feature_disabled (no lookalikes flag), 400 lookalikes_unavailable (not switched on
yet), 400 too_many_seeds, 400 lookalike_conflict (both keys sent), 400
invalid_lookalike (no seeds, a seed with zero or two keys, a bad mode, a minGrade that is
not a whole number 1-5), 422 no_usable_seeds
(no seed resolved; the error carries lookalikeSeeds). Lookalike results are a
snapshot: a saved search, search import, saved-list source or approval filter that
carries either key is refused with 400 lookalike_not_storable, so import or save the
returned kenIds as a selection (saved_searches(operation="import_to_campaign",
campaign_id=..., selected_person_ids=[...])).
search-places
Write. Early access: needs search_places on for the workspace. POST https://api.ken.so/v1/search/places
Body (json): area object, categories array, claimed boolean, country string, cursor string, hasPhone boolean, hasWebsite boolean, lang string, limit integer, location string, minRating number, minReviews integer, openNow boolean, priceLevels array, query string
Search Google Maps places (local businesses) by query and area. Costs 1 credit per page of up to 200 places. Staff, search_places flag.
POST /api/v1/search/places. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
query is what to look for ("dentists"), required unless cursor is set. Give the area as
location (city, region or address) or as lat and lng (both, optional zoom 3-21, default 13);
lat and lng win. country is a two-letter code, lang a language code. limit is the page size,
1-200, default 200. cursor is pagination.nextCursor from the previous page and carries that
page's query, area, country, lang and limit.
Free filters on the page: min_rating (0-5), min_reviews, has_website (default true keeps only
places with a website; false keeps all), has_phone, open_now,
price_levels (["$", "$$"]), claimed, categories. fetched counts the page before filtering.
Cost: each page is 1 credit (1,000 millicredits) whatever the count, also when it comes from
Kenso's 30-day store (charge.fromStore). The same page again the same UTC day, or an empty
stored page, is free. Not enough credits is a refusal before any search. A Google Maps data
failure is service_unavailable and nothing is charged.
Returns data.places (id plc_..., name, location, address, phone, website, domain, rating,
categories, hours, alreadyProcessed, accountId and more), data.fetched,
data.charge {credits, millicredits, fromStore}, data.center {lat, lng, zoom} and
data.pagination {hasMore, nextCursor}. alreadyProcessed: a workflow processed the place here;
accountId is the account it created. Open a place with search(operation="get-place");
reviews and photos are on saved_searches (place-reviews, place-photos). For every place
across whole countries or the world, run a bulk pull: place_pulls(operation="estimate-place-pull").
enrich
Write.
Unsupported direct Search enrichment (people/companies/csv) via MCP.
Unsupported direct Search enrichment tool.
Kenso Search exposes enrichment only on internal-service routes. MCP search
clients use caller user-token auth, so this tool does not call the Search API.
It returns a structured unsupported envelope with recovery guidance.
### kind=csv
Args:
file_path: CSV path retained for backward-compatible tool schema
### kind=people
Args:
campaign_id: The campaign ID these contacts belong to
contacts: Optional list retained for backward-compatible tool schema:
- contactId (int, required): The contact ID in Ken Scraping
- linkedInUrl (str, optional): LinkedIn profile URL (best match signal)
- firstName (str, optional): Contact's first name
- lastName (str, optional): Contact's last name
- fullName (str, optional): Contact's full name
- companyName (str, optional): Current company name
### kind=companies
Args:
campaign_id: The campaign ID these companies belong to
companies: Optional list retained for backward-compatible tool schema:
- companyId (int, required): The company ID in Ken Scraping
- linkedInUrl (str, optional): Company LinkedIn page URL (best match signal)
- domain (str, optional): Company website domain
- companyName (str, optional): Company name
Returns:
A structured unsupported envelope with recovery guidance.
job_changes
Read.
Unsupported direct Search job-change lookup tool.
Unsupported direct Search job-change lookup tool.
Kenso Search exposes batch month-over-month job-change detection
(POST /v1/search/job-changes) only on internal-service routes - it is consumed
by ken-backend's monthly JobChange trigger sweep, authenticated with a shared
internal-service token. MCP search clients use the caller's user-token auth, so
this tool does not call the Search API.
To act on job-change signals as a CSM, use the Trigger system instead:
triggers(operation='triggers-create', signal_type='job_change',
parameters='{"recencyDays": N}').
Args (retained for a backward-compatible tool schema):
linkedin_urls: LinkedIn profile URLs to check for employer changes
since_month: Optional "yyyy-MM"; only changes detected on/after this month
Returns:
A structured unsupported envelope with recovery guidance.