Job Postings job_postings
Job postings from public ATS boards. search is one call with the request's titles and places in body, as {"titles": {"include": ["VP Sales"]}, "location": {"countries": ["DE"]}}. resolve-filters is autocomplete for half-typed text (body {"titles": "account ex"}), not a step before search: whole titles and places go straight into search. linkedin-job-searches-create searches LinkedIn itself (the user's seat, else Kenso's data provider for credits) with ken-jobs merged in.
Call it from an MCP client connected to https://mcp.ken.so/mcp: reads go through job_postings_read and changes through job_postings_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: linkedin-job-searches-create, export, get, linkedin-job-searches-get, linkedin-jobs-get, get-export-allowance, triggers-preview, resolve-filters, search, triggers-test-fire
linkedin-job-searches-create
Write. POST https://api.ken.so/v1/linkedin-job-searches
Body (json): companies array, cursor string, datePosted string, keywords string, limit integer, location string, seniority array, workplaceType array
Search LinkedIn jobs: who is hiring for a role, where, and at which companies. Runs on the user's own LinkedIn seat for free. Without a seat it uses Kenso's data provider: 150 millicredits a row (3.75 credits per 25 rows; free on the workspace's own provider key). Confirm the cost with the user before a search that may spend credits. ken-jobs rows are merged in.
POST /api/v1/linkedin-job-searches. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Needs the linkedin_job_search workspace flag (404 while off).
Path: the caller's own connected LinkedIn seat first (via "seat", free). When
there is no seat that can read now (none, paused, LinkedIn throttling it or
reporting it unavailable) the same call goes to Kenso's data provider (via "social_data"),
charged 150 millicredits (0.15 credits) per delivered row: about 3.75 credits
per 25 rows, and nothing when the workspace uses its own provider key.
With that provider off it answers ken-jobs rows only (via "ken_jobs_only").
ken-jobs rows come after the LinkedIn rows on a first page. Read a job's detail
with linkedin-jobs-get.
Fields:
- keywords (required): the role or words, e.g. "sdr", "account executive".
- location: free text, e.g. "Germany", "Berlin". Default: anywhere.
- companies: up to 10 company names (or LinkedIn company ids on a seat).
- date_posted: past_day, past_week or past_month.
- workplace_type: on_site, remote, hybrid.
- seniority: internship, entry_level, associate, mid_senior_level, director,
executive.
- limit: LinkedIn rows, 1 to 100 (default 25).
- cursor: next_cursor of an earlier seat search with the same filters. Kenso's
data provider answers in one batch with no cursor.
Returns data {id, status, via, rows, nextCursor, creditsCharged, createdAt}.
status "running" means Kenso is still collecting the data (it can take a minute or
two): call linkedin-job-searches-get with the id until it is "completed". "failed" keeps the ken-jobs
rows and charges nothing. A row is {source (linkedin or ken_jobs), id, title,
company {name, linkedinUrl, domain}, location, postedAt, url, easyApply,
fewApplicants, applicants, description}. The same search within 24 hours answers
from the cache for free.
Errors: 402 out of credits (provider path only), 409 linkedin_seat_required
(a seat cursor, or only LinkedIn company ids, when no seat can read), 429 rate_limited (the seat is pacing
its reads; wait for Retry-After, there is no paid fallback) or quota_exceeded
(25 searches a day per workspace), 400 for a location LinkedIn does not know.
Example: operation="linkedin-job-searches-create", keywords="sdr",
location="Germany", date_posted="past_week", client_id=123
export
Write. POST https://api.ken.so/v1/job-postings/search/export
Export job postings as JSON or CSV. Metered, so browse with search first. Public. Use search for browsing and export only when the user wants the rows as a file. body needs at least one filter, plus format (json or csv) and limit.
POST /api/v1/job-postings/search/export. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id.
Use search for browsing, which is free. Export only when the user wants the
postings as a file or needs every match in full.
Metered. The monthly allowance is the workspace's lead limit, in rows per
calendar month (UTC): a workspace that may add 10,000 contacts a month may
export 10,000 rows. Exporting does not use credits. Workspaces that bypass
limits are unlimited. Call get-export-allowance (a read operation) first to see
the real limit and what remains. One export returns at most 5,000 rows, and
each returned row uses one row of the allowance.
body takes the same filters as search, and at least one filter is required
(filter_required otherwise). It has no cursor, groupBy, or includeFacets. Extra
fields:
- format: "json" (default) or "csv".
- limit: 1-5000, default 100. limit is a cap on matches, not a page size. The
export runs only when every matching posting fits: if more postings match
than the effective limit (the smaller of limit, 5000, and the rows left
this month), the call fails with export_limit_exceeded, returns nothing,
and uses no allowance. Run search with totalMode "exact" first, narrow the
filters to what the user needs, then set limit to that total. Do not set 5000
by default.
Every exported row carries the full description, so the result is large: 100
rows can run to hundreds of kilobytes. Keep the match set as small as the
request allows.
Exports are not idempotent. Each successful call is charged, and a call that
times out may still finish and charge. After a timeout or network error, call
get-export-allowance to see whether rows were used before retrying.
Returns: format "json" returns data {signals: [job], total}. format "csv"
returns {format: "csv", rowCount, csv}, where csv is the file text with a header
row and rowCount comes from the X-Ken-Row-Count header.
Errors. A plan refusal (no allowance left this month) is code
JOBS_EXPORT_ROWS_LIMIT_REACHED with metric jobs_export_rows and the used,
limit, and remaining counts. It resets on the first of the next month. Use
search meanwhile. A match set above the limit is export_limit_exceeded with
count and limit. A body with no filter is filter_required. A body with a
malformed filter, or a filter list over 100 items, is a validation error that
names the field. None of these use allowance. 503 service_unavailable means job
postings are off or the index is down: tell the user and do not retry in a loop.
504 upstream_timeout means the index was too slow: retry once with narrower
filters, after checking get-export-allowance.
Example: operation="export", body={"companies": {"include": ["acme.com"]},
"format": "csv", "limit": 40}, client_id=123
get
Read. GET https://api.ken.so/v1/job-postings/{jobPostingId}
Path: jobPostingId
Get one job posting with its raw source document and revisions. Public and free. job_posting_id is the posting id from search. Closed postings stay readable.
GET /api/v1/job-postings/{jobPostingId}. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Does not use the export allowance.
job_posting_id is the posting id from search or export (letters, digits,
hyphen, and underscore, up to 64 characters). Returns data {job, raw, revisions}. job is
the full posting with its description. raw is the latest source document as
stored. revisions lists earlier versions of the title, location, salary, and
description, newest first. A missing id is not_found.
Example: operation="get", job_posting_id="123456", client_id=123
linkedin-job-searches-get
Read. GET https://api.ken.so/v1/linkedin-job-searches/{linkedInJobSearchId}
Path: linkedInJobSearchId
Get a LinkedIn job search by id, finishing a running search. Call it until status is "completed" or "failed". Searches are kept 24 hours.
GET /api/v1/linkedin-job-searches/{linkedInJobSearchId}. Public. Sends
Ken-Version 1.1 and X-Ken-Workspace-Id.
linkedin_job_search_id is the id linkedin-job-searches-create returned (ljs_ and
32 hex digits).
Returns the same data as create. While status is "running" each call checks
the provider once; when it is ready the rows are merged in and charged once.
Another workspace's id or an expired one is not_found.
Example: operation="linkedin-job-searches-get",
linkedin_job_search_id="ljs_0123456789abcdef0123456789abcdef", client_id=123
linkedin-jobs-get
Read. GET https://api.ken.so/v1/linkedin-jobs/{linkedInJobId}
Path: linkedInJobId
Get one LinkedIn job's description and applicant count on the user's own seat. Free. Only for a linkedin row from a seat search; rows from Kenso's data provider already carry the description.
GET /api/v1/linkedin-jobs/{linkedInJobId}. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Needs the linkedin_job_search workspace flag.
linkedin_job_id is the id of a row whose source is linkedin (digits). Reads it on
the caller's own connected LinkedIn seat, one read of the seat's daily budget.
Returns data {id, title, companyName, location, state, description,
applicantCount, viewCount, postedAt, applyUrl}.
Errors: 409 linkedin_seat_required when the caller has no seat that can read now
(there is no paid path), 429 rate_limited while the seat paces its reads, 404
when LinkedIn has no such job.
Example: operation="linkedin-jobs-get", linkedin_job_id="4012345678", client_id=123
get-export-allowance
Read. GET https://api.ken.so/v1/job-postings/export-allowance
Get this workspace's job postings export allowance for the current month. Public and free. Returns limit, used, remaining, and maxPerExport. Check it before export. The allowance resets on the first of each month, UTC.
GET /api/v1/job-postings/export-allowance. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id.
Returns data {limit, used, remaining, maxPerExport, isUnlimited, periodStart,
periodEnd}. limit is the workspace's lead limit (its operator override, else its
plan's lead limit), in rows per calendar month. used includes exports still
running. remaining is what export can still spend. isUnlimited is true when the
workspace bypasses limits or its lead limit is unlimited: export is then not
capped by the month, and remaining is 2147483647, so ignore limit and remaining.
maxPerExport is the most rows one export returns (5,000). periodEnd is when the
allowance resets. Search, get, and resolve-filters never use it.
Example: operation="get-export-allowance", client_id=123
triggers-preview
Read. POST https://api.ken.so/v1/triggers/preview
Body (json): cursor string, limit integer, parameters any JSON, signalType string
Preview a trigger gate on live data: pass counts per step, sample rows, estimated credits. Public. Saves nothing, fires nothing, charges nothing. Requires campaigns edit.
POST /api/v1/triggers/preview. Sends Ken-Version 1.1 and X-Ken-Workspace-Id.
signal_type is fundraising, open_roles (companies hiring for jobTitles) or
company_headcount_growth. Any other signal returns validation_failed with
details[0].code preview_not_supported. parameters is a JSON object or a JSON
object string with the keys a trigger stores (same as triggers-create), validated
the same way. limit is 1 to 25 companies (default 25); page on with
pagination.nextCursor.
Every page returns:
- companies: sample rows on this page (open_roles: kenCompanyId, name, domain,
openJobCount, up to 3 jobs; company_headcount_growth: headcount before and now,
growthAbs, growthPct; fundraising: the raise and its named executives).
- total: the source's own count across pages (null for open_roles).
- steps: [{name, count, description}] for this page, in gate order. open_roles:
job_filter, resolved_company, min_company_size (minCompanySize and maxCompanySize on
the current headcount; all pass when neither is set), people_filter,
max_contacts_per_company.
company_headcount_growth: min_growth_pct, min_growth_abs, min_company_size,
people_filter, max_contacts_per_company. fundraising: funding_filters,
max_contacts_per_company. people_filter counts the people at the passing
companies who match titles, excludeTitles, seniorityLevels, functions and
countries (null when Kenso Search did not answer). max_contacts_per_company is
the most people this page can import.
- estimatedCredits: {isEstimate: true, leads, credits, totalMillicredits, lines,
basis}. An upper bound for this page: max_contacts_per_company people at the
leads rate of billing credit-estimates-create (about 1.45 credits a lead).
basis says how it was computed. Contacts already in the workspace are not
charged as leads.
Example: triggers-preview with signal_type="open_roles",
parameters='{"jobTitles": ["Account Executive"], "minOpenJobs": 2,
"titles": ["VP Sales"], "countries": ["United States"], "maxContactsPerCompany": 2}'.
resolve-filters
Read. POST https://api.ken.so/v1/job-postings/filters/resolve
Resolve partial company, title, and location text into search filter values. Public and free. body takes companies, titles, locations, and limit. Use it before search to get company ids, domains, and exact title and place names.
POST /api/v1/job-postings/filters/resolve. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Does not use the export allowance.
Autocomplete for filter values. body is {companies: "acm", titles: "account
ex", locations: "san fr", limit: 10}. Send at least one of companies, titles,
or locations, each a partial text string. limit is 1-25, default 10. It needs
no search filter. Matching is by prefix and word start, case-insensitive,
ranked by count.
Returns data {companies: [{id, name, domain, open_jobs}], titles: [{value,
count}], locations: [{value, kind, count}]}. kind is country, region, state,
or city. Pass company ids in search companies.ids, and titles and locations
in titles.include and location.
Example: operation="resolve-filters", body={"companies": "acm", "titles":
"account ex"}, client_id=123
search
Read. POST https://api.ken.so/v1/job-postings/search
Search job postings scraped from public ATS boards and job feeds. Public and free. body needs at least one filter (titles, companies, location, salary, seniority, hasRemote, postedWithin, sources). Browse here, export later. Pass includeDescription false when browsing.
POST /api/v1/job-postings/search. Public. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. Does not use the export allowance.
The index holds job postings scraped from public ATS boards and job feeds:
Greenhouse, Lever, Ashby, Workable, Gem, Rippling, Polymer, Recruitee,
Teamtailor, Personio, Pinpoint, YC, Hacker News (hn), Himalayas, and a few
newsletters. It is global, not per workspace. Use it to find companies that
are hiring for a role and to read the postings themselves.
body is the request object. At least one filter is required, or the call
fails with filter_required. Filters:
- titles {include: [...], exclude: [...], vector: bool}. Phrase match on word
boundaries: "account executive" matches "Senior Account Executive, EMEA".
- companies {include: [domains or names], exclude: [...], ids: [company ids]}.
Use resolve-filters to turn partial names into ids and domains.
- location {countries: ["US"], regions: [...], states: ["CA"], cities: ["San
Francisco"]}.
- tags {include: [...], exclude: [...]}.
- salary {min_usd, max_usd}. Set only when the source states a USD amount.
- seniority: list of EN (entry), MI (mid), SE (senior), EX (executive).
- languages: lowercase codes such as "en".
- hasRemote: true for remote roles.
- postedAfter, postedBefore: yyyy-MM-dd or ISO 8601. postedWithin: days, 1-3650.
- sources: source keys such as "greenhouse", "lever", "ashby", "workable", "yc", "hn".
- status: "open" (default), "closed", or "all".
- includeAgencies: false by default, which hides recruiting and staffing agencies.
Options: limit 1-50 (default 25). cursor: pass pagination.next_cursor from the
previous page with the same filters. totalMode: "none", "capped" (default,
counts to 1,000), or "exact". mode: "fast" (default) or "deep", which also
matches the title phrase in descriptions, company names, and locations.
includeDescription (default true, but pass false when browsing: descriptions are
long and make pages large), includeCompany
(default true), includeFacets (adds counts by source, country, seniority,
remote, and status). groupBy: "company" returns one row per company under
companies, each with match_count, newest_posted_at, sources, and up to 20
matching titles.
Returns data {signals: [job], total, totalMode, pagination: {next_cursor},
facets, notes}. A job has id, title, description, company {id, name, domain,
website_url, linkedin_url}, location, country, remote, workplace_type,
department, seniority, salary_min_usd, salary_max_usd, source, application_url,
status, posted_at, first_seen_at, last_seen_at, closed_at. Pass a job id as
job_posting_id to get for the raw source document and revisions.
Errors: 503 service_unavailable means job postings are off or the index is
down. Tell the user and do not retry in a loop.
Example: operation="search", body={"titles": {"include": ["account
executive"]}, "location": {"countries": ["US"]}, "hasRemote": true,
"postedWithin": 14, "includeDescription": false, "limit": 25}, client_id=123
triggers-test-fire
Read. POST https://api.ken.so/v1/triggers/{triggerId}/test-fire
Path: triggerId
Body (json): campaignId integer, contactId integer, occurredAt date-time, payload any JSON
Test-fire a saved trigger against a sample signal: would it fire, and why. Public. No firing, no cooldown, no send, no charge. Requires campaigns edit.
POST /api/v1/triggers/{triggerId}/test-fire. Sends Ken-Version 1.1 and
X-Ken-Workspace-Id. The sample signal has the trigger's own signal type and is
evaluated the way an arriving signal is, read-only: nothing is queued, no cooldown
is taken, no firing row is written, window counters do not change. Recent signals
are not replayed; the sample is the only input.
contact_id is required and must be in the workspace. campaign_id is the campaign
the sample came from (the audience filter matches on it). payload is the signal's
JSON object, e.g. {"clickedUrl": "https://..."} for link_clicked or
{"classification": 0} for reply_received. occurred_at is ISO 8601 within the last
365 days; omit it for now.
Returns shouldFire, rejectedBy (the first failed check or null), checks
[{name, passed, message}] in order status, audience_filter, parameters, cooldown
(every check runs; status fails for a paused or archived trigger and for one whose
campaign is deleted), evidence (what the firing would carry, when parameters passed)
and scheduledFor. A firing can still be suppressed later (do not contact,
blocklist, frequency cap). Supported: email_opened, link_clicked, reply_received,
lead_uploaded, webhook_lead_received, job_change, company_headcount_growth,
open_roles and fundraising. An open_roles or fundraising payload names the trigger
the way its sweep does: {"triggerDefinitionId": <trigger_id>, "targetCampaignId":
<the trigger's campaign>, ...}. Signals that only a scheduled sweep fires (for
example click_dormancy, company_icp_timing, linkedin_post_engagement) return
validation_failed with details[0].code test_fire_not_supported.