Search jobs
jobs_searchSearch real-time job listings by title, location, company, and filters to find matching roles and return job details.
Instructions
Searches a database for real-time job listings matching the user's criteria.
The query is the full job title or role: "Ruby Developer" or "Ruby on Rails Engineer" rather than a bare keyword like "Ruby", which is too broad and matches unrelated fields. 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. The response also carries a nextCursor for the next page of
results; a follow-up page is fetched by passing only that cursor, with no other search parameters.
With a ready profile, a query for the profile's target profession or an omitted query uses the same personalized feed as jobs_recommendations and the website. A different or unrecognized profession uses general job search, preserving the explicit query and filters. An omitted location uses the profile location. Without a ready profile, search uses the general job listings. 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.
Constraints in the user's request — remote-only work, H1B sponsorship, a minimum salary, hiding risky postings, a minimum match grade — are the search parameters remote, h1b_sponsors_only, salary_floor, hide_low_quality, and min_match; sort orders the results by relevance, newest, salary or personal match. The search enforces only constraints passed as parameters; a constraint left out of the call is not applied to the result set.
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 never returns hybrid jobs. A job that does not state the filtered attribute is left out while that filter is set. Fully remote work that can be done from the requested location is strict_remote, with confirmed_work_from to require a stated work-from area; one brand inside a company is hiring_brand next to company.
Advanced filters (sort, min_match, h1b_sponsors_only, hide_low_quality, salary_floor, remote, strict_remote, confirmed_work_from, work_modes, benefits, bonuses_only, companies, exclude_companies; sort only when ordering by salary or match, companies only when it names more than one employer) apply for every account. Without FoundRole Pro, a search using one returns the first few matching jobs and the number of further matches; FoundRole Pro accounts receive the whole list. The other parameters never shorten the results.
Each response includes a system_instruction describing how to present the results for the current client.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Result order (score, posted_at, match, salary): score is relevance and the default, posted_at is newest first, 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") | |
| cursor | No | Pagination cursor. Treat as an opaque string. COPY EXACTLY. | |
| 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 | |
| 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. | |
| strict_remote | No | Advanced filter: only postings checked as fully remote that can be worked from the requested location: the posting names that area, allows anywhere, or does not say where. Stricter than remote; work_modes other than remote do not apply with it. | |
| posted_days_ago | No | Number of days ago to search for jobs (1-365) | |
| employment_types | No | Filter: jobs offered as any of these employment types (full_time, part_time, contractor, temporary, intern, volunteer, per_diem, other). | |
| hide_low_quality | No | Advanced filter: hides postings with a risky ghost grade (D/F); ungraded postings stay. | |
| 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). 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. | |
| h1b_sponsors_only | No | Advanced filter: only companies known to sponsor H1B visas. | |
| confirmed_work_from | No | Advanced filter: with strict_remote, also leaves out postings that do not say where the work can be done from. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | No | ||
| preview | No | ||
| feedKind | No | ||
| feedStatus | No | ||
| continueUrl | No | ||
| jobSearchId | No | ||
| resultSetId | No | ||
| statusOrder | No | ||
| revalidating | No | ||
| resultBatchId | No | ||
| trackerWebUrl | No | ||
| profileSetupUrl | No | ||
| profileSetupState | No | ||
| lowRelevanceNotice | No | ||
| system_instruction | No |