Search jobs
jobs_searchSearches a database for real-time job listings matching the user's criteria.
The query is the full job title or role: "Ruby Developer" rather than a bare keyword like "Ruby", which is too broad and matches unrelated fields. roles_lookup turns words that name no exact role into FoundRole roles with their job counts. Results may be filtered by location, company, and how recently a job was posted.
Each result carries an id and resultItemId; jobs_details takes that id with the corresponding
result_item_id and returns the job's full description, requirements, and benefits. One call returns one answer: there is no next page, and the
response links to the same search on the FoundRole website for the rest of the list.
With a ready profile, an omitted query uses the same personalized feed as jobs_recommendations and
the website; a query is a general job search that preserves the explicit query and filters. An
account's saved role is reported in every response as savedRole; an omitted query or the saved
role's title searches exactly that role, and any other query leaves the saved role unchanged. A search without a location runs in the place saved on the account, widened to its
country when few jobs are posted near that city; an account with no saved place searches where the
user is now when the client reports it, otherwise the default country. Such a response names the place
searched as searchedPlace. A response for a request that names no exact role can carry a guide
question the widget shows to the user. Job details include
FoundRole salary benchmarks, H-1B sponsorship signals, E-Verify status, and job-trust analysis;
list-level employer signals follow the user's current entitlements. Pay estimates, real-or-ghost
grades and visa records are FoundRole figures, attributed once per response in
figureSources: source (FoundRole), methodologyUrl (the FoundRole page
that explains how they are computed) and, for each kind of figure the listed jobs carry
(estimatedSalary, ghostScore, and visaRecords for h1bSponsor, eVerify
and h1bPetitions), its basis (what it is computed from) and section link; knowledge_search returns
the same explanation. A pay estimate's posting count is that job's estimatedSalary.sampleSize, and
estimatedSalary.basedOn names the postings it was built from (the same role in the same area, or a
wider match when that area has too few). A false
h1bSponsor or eVerify means no record was found in those files, not that the employer does not
sponsor; a job without them carries no visa claim.
Constraints in the user's request — remote-only work, H1B sponsorship, a minimum salary, a minimum match grade — are the search parameters remote, h1b_sponsors_only, salary_floor, and min_match. The search enforces only constraints passed as parameters; a constraint left out of the call is not applied to the result set.
Every request is ordered by relevance to the query. The sort parameter (score, posted_at, match, salary) replaces that order: posted_at orders by posting date and does not rank by fit to the query, salary orders by pay and match by personal fit. posted_days_ago is a posting window: it removes every job older than the window from the answer, so a narrow window can leave the answer empty.
Job type, work mode, required education, experience level, benefits, bonuses, employers to include or exclude, and the search radius are the parameters employment_types, work_modes, education, experience_levels, benefits, bonuses_only, companies, exclude_companies and radius. Remote and hybrid are independent work modes: a remote search returns hybrid jobs only as marked additions to a short answer. A job that does not state the filtered attribute is left out while that filter is set. One brand inside a company is hiring_brand next to company.
A company name that several employers share covers all of them, and the response names each with its domain; an employer's domain in place of a name (company, companies or exclude_companies) means that employer alone.
When fewer than 4 jobs match, the answer is widened and each added job carries widened,
the condition that was widened (window, radius, hybrid). A search limited by posted_days_ago adds
jobs from the next longer window, up to no window; a city search that matched nothing adds jobs within
100 miles; a remote search adds hybrid jobs in its place. Jobs that met the request as asked
come first, and widening states how many there were and what each step added. Experience level, job type, pay floor,
employer, visa sponsorship and every other filter are never widened.
Advanced filters (sort, min_match, h1b_sponsors_only, salary_floor, remote, work_modes, benefits, bonuses_only, companies, exclude_companies; sort when it orders by salary or match, companies when it names more than one employer) apply for every account. One answer lists the first matching jobs and states how many further jobs match.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "jobs_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Result order (score, posted_at, match, salary): score is relevance to the query and the order of every request that sets no sort; posted_at orders by posting date and does not rank by fit to the query; salary is highest pay first; match is best personal fit first and needs a resume. Ordering by salary or match is an advanced option. | |
| query | No | The full job title or skill (e.g., "Ruby Developer", NOT just "Ruby") | |
| radius | No | Search radius in miles around a city location (default 40); not used for state, country or remote searches. | |
| remote | No | Advanced filter: only remote-eligible jobs, matched across the whole country of the requested location rather than its radius. | |
| company | No | The official company name, or the domain of one employer | |
| benefits | No | Advanced filter: benefit names such as "health insurance", "401k" or "parental leave"; a job qualifies only when it states every listed benefit. Names that match no known benefit are ignored. | |
| location | No | Geographic location (e.g., 'Boston, MA') | |
| companies | No | Filter: official company names; a job from any of them qualifies, across every job board each employer posts on. More than one company makes it an advanced filter. Next to company, a job has to match both; hiring_brand narrows company only. | |
| education | No | Filter: jobs whose posting requires one of these education levels (no_requirements, high_school, associate_degree, bachelor_degree, professional_certificate, postgraduate_degree); bachelor_degree means the posting asks for a bachelor degree, not that it suits someone holding one. | |
| min_match | No | Advanced filter: lowest personal FoundRole match grade to keep, the same letter each job shows in insights.match.grade. A and A- are rare even for a strong resume; B keeps good and strong matches; C+ also keeps fair ones. Needs a resume on the account. | |
| work_modes | No | Advanced filter: jobs in any of these work modes (on_site, remote, hybrid). remote is matched across the whole country of the location, the others within the radius. ["remote"] is the same search as remote: true. | |
| bonuses_only | No | Advanced filter: only jobs that state a bonus (sign-on, performance, referral, commission and the like). | |
| hiring_brand | No | Filter: one brand inside the company, for example company "Google" with hiring_brand "YouTube"; used only together with company. | |
| salary_floor | No | Advanced filter: minimum annualized salary in USD; a posting qualifies when the lower bound of its pay band reaches the floor. Jobs without a USD salary are dropped. | |
| posted_days_ago | No | Posting window in days (1-365): every job posted earlier than that many days ago is removed from the answer, so a narrow window can leave the answer empty. | |
| employment_types | No | Filter: jobs offered as any of these employment types (full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other). | |
| exclude_companies | No | Advanced filter: official company names whose jobs are removed from the results, across every job board each employer posts on. | |
| experience_levels | No | Filter: jobs at any of these experience levels (entry_level, mid_level, senior_level, executive, level_not_stated). The level comes from the years of experience the posting asks for and the seniority in its title, the higher of the two; entry_level never includes a posting asking for more than two years. level_not_stated selects jobs whose level cannot be derived; it can be selected alone or alongside other levels. | |
| h1b_sponsors_only | No | Advanced filter: only companies known to sponsor H1B visas. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | No | ||
| guide | No | ||
| preview | No | ||
| feedKind | No | ||
| widening | No | ||
| savedRole | No | ||
| feedStatus | No | ||
| continueUrl | No | ||
| jobSearchId | No | ||
| resultSetId | No | ||
| statusOrder | No | ||
| revalidating | No | ||
| figureSources | No | ||
| resultBatchId | No | ||
| searchedPlace | No | ||
| trackerWebUrl | No | ||
| profileSetupUrl | No | ||
| appliedConditions | No | ||
| profileSetupState | No | ||
| lowRelevanceNotice | No |