jobs_search
Find job listings that match your criteria by searching live postings, with filters for location, company, remote work, salary, and H1B sponsorship.
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; jobs_details takes that 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.
Authenticated results include resume match data when a profile is available. 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.
Advanced constraints in the user's request — remote-only work, H1B sponsorship, a minimum salary, hiding risky postings, a minimum match score — are the search parameters remote, h1b_sponsors_only, salary_floor, hide_low_quality, 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. FoundRole Pro accounts receive the screened list; other accounts receive the full list and the response reports that the advanced filters were not applied.
Each response includes a system_instruction describing how to present the results for the current client.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| remote | No | Advanced filter: only remote-eligible jobs (respects the location/region scope). | |
| company | No | The official company name | |
| location | No | Geographic location (e.g., 'Boston, MA') | |
| min_match | No | Advanced filter: minimum personal FoundRole match score (0-100); needs a resume on the account. | |
| salary_floor | No | Advanced filter: minimum annualized salary in USD; a posting qualifies when the midpoint of its pay band reaches the floor. Jobs without salary data are dropped. | |
| posted_days_ago | No | Number of days ago to search for jobs (1-365) | |
| hide_low_quality | No | Advanced filter: hides postings with a risky ghost grade (D/F); ungraded postings stay. | |
| h1b_sponsors_only | No | Advanced filter: only companies known to sponsor H1B visas. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| jobs | No | ||
| feedKind | No | ||
| feedStatus | No | ||
| jobSearchId | No | ||
| statusOrder | No | ||
| revalidating | No | ||
| trackerWebUrl | No | ||
| profileSetupUrl | No | ||
| profileSetupState | No | ||
| lowRelevanceNotice | No | ||
| proFilterUpsellUrl | No |