Kenso MCP tools

Social social

Records from LinkedIn, Facebook, Instagram, X, TikTok, YouTube and Crunchbase: lookup reads the links you have, search finds posts, jobs, people, ads and videos, resolve turns a link or a name into profiles, records lists what is stored for a contact, account or person (free). 0.15 credits a record on Kenso's key, 0 on the workspace's own key. A running result: get with its lookup_id or search_id until ready.

Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through social_read. 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: lookup, resolve, search, get, records

lookup

Read. Early access: needs social_data on for the workspace. POST https://api.ken.so/v1/social-lookups

Body (json): accountId integer, contactId integer, kind string, personId integer, urls array, waitSeconds integer

Read the records 1 to 100 social links name: profiles, company pages, channels and posts. Costs 0.15 credits per record on Kenso's key, 0 on the workspace's own key or for stored records. The result may be "running": poll social(operation="get", lookup_id=...) every few seconds.

POST /api/v1/social-lookups. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the
social_data workspace flag (404 while off) and Search edit; with contact_id also Campaigns
edit, with account_id or person_id also Accounts edit (403 permission_denied otherwise).

Fields:
- urls (required): 1 to 100 links on LinkedIn, Facebook, Instagram, X, TikTok, YouTube or
  Crunchbase. A link that is not supported is listed in unsupportedUrls and the rest are read.
- kind: "comment" reads a Facebook, Instagram, TikTok or YouTube post's comments; "review"
  reads a Facebook page's reviews; both run only on the workspace's own social data key (400
  validation_failed without one). Any other kind must be the link's own (a profile link reads
  the profile; a profile's posts are a search, e.g. type="posts_by_profile").
- contact_id, account_id, person_id: link the records to that record of this workspace. A
  LinkedIn profile also fills its empty LinkedIn field. Another workspace's id is not_found.
- wait_seconds: 0 to 50 before answering "running"; omit it to wait 65.

Price: 0.15 credits per record read on Kenso's key; 0 on the workspace's own social data key
(Settings, Integrations); 0 for a link read before (a profile, company page or channel for 7
days, anything else for 24 hours). A failed or empty read costs nothing.

Returns data {id (slk_...), status (ready, running, failed), records, recordCount,
creditsCharged, keySource (kenso, workspace, cache), errorCode, unsupportedUrls, createdAt}.
A record is {id, platform, kind, url, externalId, handle, name, text, postedAt, metrics
{followers, likes, comments, shares, views}, data, fetchedAt}; data holds platform fields,
which vary by platform. "running" means Kenso is still reading: call social(operation="get",
lookup_id=<id>) until it is "ready".

Errors: 400 validation_failed, 402 insufficient_credits, 422 unsupported_link (no link is
supported), 424 provider_key_failed (the workspace's own key failed: check it in Settings,
Integrations), 429 daily_limit_reached, 503 social_data_unavailable.

Example: operation="lookup", urls=["https://www.linkedin.com/in/jane-doe"], contact_id=123

resolve

Read. Early access: needs social_data on for the workspace. POST https://api.ken.so/v1/social-resolutions

Body (json): accountId integer, company string, contactId integer, knownUrls array, name string, personId integer, url string

Resolve a social link to its canonical profile (free), or a person's name to candidate LinkedIn profiles. A first and last name runs a people search at 0.15 credits per record on Kenso's key (0 on the workspace's own key). Candidates always come back; a warning says when the search did not run, failed or is still running.

POST /api/v1/social-resolutions. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the
social_data workspace flag (404 while off) and Search edit; with contact_id also Campaigns
edit, with account_id or person_id also Accounts edit (403 permission_denied otherwise).

Send url, or name:
- url: a social link; returns data.link {platform, kind, url, handle, externalId}. Free.
- name: the person's name. A first and last name runs a LinkedIn people search; one word answers
  only from known_urls and the profiles already stored for the record.
- company: the person's company, to rank candidates.
- known_urls: links you already hold for the person.
- contact_id, account_id, person_id: the record the person is; its stored profiles count as
  evidence. Another workspace's id is not_found.

Returns data {link, candidates [{url, platform, name, headline, confidence (0 to 1), evidence
[...]}], searchId (ssr_..., the people search it ran), creditsCharged, warning {code,
message}}. warning.code is validation_failed (one-word name: the search did not run),
search_running (resolve again in a minute: the finished search answers free) or the code the
search failed with.

Errors: 400 validation_failed (no url or name, or a one-word name with no candidates), 402
insufficient_credits, 422 unsupported_link, 424 provider_key_failed, 429 daily_limit_reached,
503 social_data_unavailable.

Example: operation="resolve", name="Jane Doe", company="Globex", person_id=123

Read. Early access: needs social_data on for the workspace. POST https://api.ken.so/v1/social-searches

Body (json): company string, country string, firstName string, keyword string, lastName string, limit integer, location string, platform string, since date-time, type string, url string

Run one social search: posts by a profile or company, jobs, people by name, ads, videos and more. Costs 0.15 credits per record on Kenso's key, 0 on the workspace's own key or for a repeat within 24 hours. The result may be "running": poll social(operation="get", search_id=...) every few seconds.

POST /api/v1/social-searches. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the
social_data workspace flag (404 while off) and Search edit.

Fields:
- platform (required): linkedin, facebook, instagram, x, tiktok, youtube or crunchbase.
- type (required): posts_by_profile, posts_by_company, jobs_by_keyword, jobs_by_company,
  people_by_name, posts_by_page, posts_by_group, ads_by_keyword, profile_by_username,
  posts_by_keyword, profiles_by_search, channels_by_keyword, videos_by_keyword,
  videos_by_hashtag, videos_by_channel, companies_by_keyword. Not every type runs on every
  platform; a missing field or a type the platform lacks is 400 validation_failed naming it.
- url: the profile, company, page, group or channel link a ..._by_profile, ..._by_company,
  ..._by_page, ..._by_group or ..._by_channel search reads.
- keyword: the words, username or hashtag a ..._by_keyword, ..._by_username, ..._by_hashtag
  or profiles_by_search search reads.
- location: a place for a job or people search ("Berlin", "United States").
- country: two-letter country code ("us", "de").
- company: a company name (jobs_by_company). people_by_name reads only first_name and
  last_name.
- first_name, last_name: people_by_name.
- since: only records posted at or after this ISO-8601 instant.
- limit: 1 to 100 records (default 25).

Price: 0.15 credits per record read on Kenso's key; 0 on the workspace's own social data key;
0 for the same search within 24 hours (keySource "cache", the first search's id).

Returns data {id (ssr_...), status (ready, running, failed), platform, type, records,
recordCount, creditsCharged, keySource, errorCode, createdAt}; records as in lookup.

Errors: 400 validation_failed, 402 insufficient_credits, 424 provider_key_failed, 429
daily_limit_reached, 503 social_data_unavailable.

Example: operation="search", platform="linkedin", type="posts_by_company",
url="https://www.linkedin.com/company/globex", limit=10

get

Read. Early access: needs social_data on for the workspace. GET https://api.ken.so/v1/social-lookups/{socialLookupId}

Path: socialLookupId

Get a lookup (lookup_id) or a search (search_id), collecting the records that are ready. Free. Call it every few seconds while status is "running".

GET /api/v1/social-lookups/{socialLookupId} or GET /api/v1/social-searches/{socialSearchId}.
Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the social_data workspace flag.

Send exactly one:
- lookup_id: the slk_ id social(operation="lookup") returned.
- search_id: the ssr_ id social(operation="search") returned, or a resolution's searchId.

Returns the same data as lookup or search. While status is "running" each call collects the
records that are ready and answers 202; a finished request answers "ready", or "failed" with
its errorCode. Another workspace's id is not_found.

Example: operation="get", lookup_id="slk_123"

records

Read. Early access: needs social_data on for the workspace. GET https://api.ken.so/v1/social-records

Query: accountId integer, contactId integer, cursor string, kind string, limit integer, personId integer, since date-time

List the social records stored for one contact, account or person, newest first. Free: it reads nothing new. Send exactly one of contact_id, account_id and person_id.

GET /api/v1/social-records. Sends Ken-Version 1.1 and X-Ken-Workspace-Id. Needs the
social_data workspace flag and Search view; for a contact also Campaigns view, for an
account or person also Accounts view (403 permission_denied otherwise).

Fields:
- contact_id, account_id or person_id (exactly one): whose records. Another workspace's id is
  not_found.
- kinds: only these kinds (profile, company, channel, post, comment, job, review, event, ad).
- since: only records Kenso read at or after this ISO-8601 instant.
- limit: 1 to 200 per page (default 50); cursor: pagination.nextCursor of the previous page.
  The list pages through the newest 1,000 records.

Returns data [records as in lookup] and pagination {nextCursor, hasMore}.

Example: operation="records", person_id=123, kinds=["post"]