What a role's postings ask for
role_requirementsWhat postings for a role or a job category ask for, counted over a sample of them: the tech skills their descriptions mention (each as a share of the sampled postings, with how many employers mention it), the minimum years they state, salary quartiles per currency, the remote share, and the companies and countries with the most of them. query is the role only, as in search_jobs ('data engineer'); the sample is the 300 postings closest to it among those the filters admit, each requisition counted once however many Boards or countries copy it, and at most 8 of one company's unless company is named. category alone samples the category's newest postings across the whole index; with query, the closest within it. Say what was counted: how many postings, of how many, and how they were picked, as the answer states it. Skills come from a fixed list of tech skills; a skill few employers mention may be one employer's self-description. For a career switcher, read the skills with the stated years. The filters mean what they mean in search_jobs, include_non_tech too: postings HeadStart's classifier is confident are not tech are left out of the sample unless it is true, and the answer says how many. No description text is returned.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | The role only, such as 'data engineer'. | |
| remote | No | Remote jobs only. | |
| company | No | A company name, matched as the site's company box matches (any company name containing the text), or a Board key from an earlier answer such as 'ashby:openai'. In search_jobs beside `category` it needs a directory company: a key such as 'greenhouse:stripe', or an exact name. | |
| country | No | ISO 3166-1 alpha-2 code (US, GB, DE, IN); a country's name or 'UK', 'USA', 'UAE' is read as its code. Matches every way a job's location names the country: its name, states, cities and codes. IN is india_place 'india'. | |
| category | No | A job category: its postings across the whole index, or with `query` the closest within it. A label or close name ('AI/ML') is read as its id. | |
| location | No | Text the job's location contains, any country. Accents and a city's other spellings read alike: Zurich finds Zürich, Bangalore finds Bengaluru. | |
| max_years | No | The user's own years of experience ('3+ years' is 3): keeps jobs asking for at most this many, and jobs that state no experience (their rows say 'experience not stated'). | |
| operators | No | Who may post the jobs, as hiring_now labels companies: employer, services (an IT services firm), staffing (an agency posting clients' contracts) or aggregator (a job board re-posting others' jobs). Staffing and aggregator are left out unless named, as on the site's Hiring now tab, or a `company` is named; the answer says how many jobs that left out. Labels come from a curated list: an unlisted company counts as an employer. | |
| has_salary | No | Only jobs that state a salary. | |
| salary_max | No | Annual; needs salary_currency. Keeps a job whose stated range starts at or below it. | |
| salary_min | No | Annual; needs salary_currency (30 lakh = 3000000 INR). Keeps a job whose stated range reaches it; other currencies are converted at fixed rates. | |
| india_place | No | An Indian city or region, or 'india' for anywhere in India. | |
| max_age_days | No | Leaves out postings older than this many days: the posted date, else the day HeadStart first saw the job. 365 unless sent; 0 for any age. | |
| employment_type | No | full-time also keeps jobs whose source states no type; part-time, contract and internship keep only jobs that say so. | |
| salary_currency | No | ISO 4217 code, such as USD, INR, EUR, GBP. | |
| include_non_tech | No | Also list the jobs HeadStart's classifier is confident are not tech (a store cashier, a plant's process engineer), which are left out unless this is true, as the site leaves them out unless its 'Include non-tech roles' switch is on. The answer says how many were left out. Send it for a role the user really wants that is not software or tech. | |
| work_authorization | No | Use this, not `keyword`, for visa sponsorship or relocation: a description that mentions sponsorship usually refuses it. offers_sponsorship: the description offers this job visa sponsorship and nothing in it refuses or hedges it; an offer limited to another country than the job's (or a move to another country's city), to levels above its title, or to full-time roles on an internship, does not count. may_offer_sponsorship: those jobs, plus the ones whose offer is hedged ('not guaranteed', 'not for every role', 'case by case', 'may be available', 'if possible', 'subject to approval', 'only if already based in'), is a visa transfer only, or names a country or level the job's place or title does not show; each row says which kind it is, so say it. refuses_sponsorship: it refuses sponsorship ('now or in the future', 'Visa Sponsorship: No'), requires citizenship of this job or work authorisation already held, or offers it only to another country or level; offers_relocation: it offers relocation help. Text-derived, not a field the employer set: HeadStart's rules (headstart.jobs.work_authorization) read each sponsorship, citizenship and relocation sentence with its negation, and read an offer against the job's place, title and type. Of 50 offers_sponsorship jobs drawn from the live index after the rules froze (ADR-0368; 25 in the US, 25 elsewhere, at most 5 a company), read strictly, 47 (0.94) offered this job sponsorship firmly and all 50 at least may; the 0.98 to 0.99 precision on 1,062 hand-read descriptions (ADR-0333 to ADR-0368) is on the rules' own tuning set. Before telling a user a job sponsors visas, read its sponsorship sentences with get_job. A posting without a description never matches. |