Search roles
search_rolesOpen intern and new-grad roles, newest posting first. Returns {data: Role[], next_cursor, total}. Pass next_cursor back as cursor for the next page. Page size is up to 20 without an API key and 100 with one. Without a Realtime key, roles first detected within the Free plan's delay (minutes in the server instructions) are left out, and employer_url and ats_job_id are null. include_evidence (Realtime) adds the posting sentences behind the sponsorship, citizenship, clearance and graduation fields.
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": "search_roles"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | Company group slugs from list_groups, any of them; an array or a comma-separated string. REST: group. | |
| level | No | Omit for both. REST: level. | |
| limit | No | Default 20. | |
| query | No | Text the role title or company name contains, matched as one phrase. REST: q. | |
| since | No | Only roles posted within this window. REST: since. | |
| track | No | Any of these tracks, as an array or a comma-separated string. "swe" covers frontend, backend and fullstack. REST: track. | |
| cursor | No | next_cursor from the previous page. | |
| degree | No | Keep roles open to this degree program: a posting that names the degrees it accepts must include it; one naming none stays in. REST: degree. | |
| company | No | Exact company name as list_companies returns it. REST: company. | |
| country | No | ISO 3166-1 alpha-2 codes, an array or a comma-separated string. Setting it replaces the US-only default. REST: country. | |
| us_only | No | Default true: roles open to US applicants. false lifts it. REST: us=0. | |
| undergrad | No | true hides roles that accept only graduate degrees. REST: undergrad=1, or degree=bachelors. | |
| workplace | No | Workplace types, any of them; an array or a comma-separated string. REST: workplace. | |
| citizenship | No | "not_required" hides roles whose posting requires US citizenship or US-person status (eligibility.citizenship_required true). Roles not read yet stay in. With include_clearance=true it keeps clearance roles that state no citizenship requirement. REST: citizenship. | |
| sponsorship | No | For an applicant who needs visa sponsorship. "needed" hides roles whose posting says no sponsorship; roles that do not say, or are not read yet, stay in. "available" keeps only roles whose posting says it sponsors. REST: sponsorship. | |
| posted_after | No | ISO 8601 time; only roles posted at or after it. | |
| graduation_year | No | Hide roles whose graduation window excludes this year. REST: grad. | |
| include_evidence | No | ||
| exclude_companies | No | Company names to leave out; an array or a comma-separated string. REST: exclude. | |
| include_clearance | No | Default false hides roles requiring US citizenship, US-person status or a clearance. REST: clearance=1. |