hh.ru APIhh.ru ↗
Search and retrieve job vacancies from hh.ru (HeadHunter). Filter by region, salary, experience, and industry. Returns full job details including skills and descriptions.
curl -X GET 'https://api.parse.bot/scraper/3ccf546c-1803-406c-902c-9e3df9fe872e/search_vacancies?area=1&text=python+developer¤cy=RUR&per_page=20&schedule=remote&employment=full&experience=between1And3' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for vacancies on hh.ru with available filters. Returns paginated results parsed from the search results page. Supports filtering by text, region, experience, employment type, schedule, and more.
| Param | Type | Description |
|---|---|---|
| area | string | Region ID (1=Moscow, 2=St Petersburg). Multiple values supported. |
| page | integer | Page number (0-indexed) |
| text | string | Search keywords (e.g., 'python developer', 'data engineer') |
| label | string | Labels: with_address, accept_handicapped, accept_kids, not_from_agency, accredited_it, low_performance |
| salary | integer | Minimum salary amount |
| currency | string | Salary currency code: RUR, USD, EUR, KZT, UAH, AZN, UZS, GEL, KGS, BYR |
| industry | string | Industry ID (numeric) |
| order_by | string | Sort order: relevance, publication_time, salary_desc, salary_asc |
| per_page | integer | Results per page |
| schedule | string | Work schedule: fullDay, shift, flexible, remote, flyInFlyOut |
| education | string | Education level: not_required_or_not_specified, secondary, special_secondary, higher, bachelor, master, candidate, doctor |
| employment | string | Employment type: full, part, project, volunteer, probation |
| experience | string | Required experience: noExperience, between1And3, between3And6, moreThan6 |
| employer_id | string | Employer/company ID |
| search_field | string | Where to search: name, company_name, description |
| search_period | integer | Publication period in days: 1, 3, 7, 30 |
| enable_snippets | string | Enable text snippets in results (true/false) |
| only_with_salary | string | Show only vacancies with salary specified (true/false) |
| professional_role | string | Professional role ID (numeric) |
{
"type": "object",
"fields": {
"page": "integer - current page number",
"found": "integer - total vacancies matching filters",
"pages": "integer - total pages available",
"per_page": "integer - results per page",
"vacancies": "array of vacancy objects with id, name, url, salary, experience, experience_id, employer, address, labels"
},
"sample": {
"data": {
"page": 0,
"found": 3179,
"pages": 3,
"per_page": 5,
"vacancies": [
{
"id": "131928728",
"url": "https://hh.ru/vacancy/131928728",
"name": "Python Developer",
"labels": null,
"salary": null,
"address": "Москва",
"employer": {
"id": "2136954",
"name": "Домклик"
},
"experience": "Опыт 3-6 лет",
"experience_id": "between3And6"
}
]
},
"status": "success"
}
}About the hh.ru API
The hh.ru API provides 2 endpoints to search and retrieve job vacancies from HeadHunter, Russia's largest job board. The search_vacancies endpoint returns paginated results with salary, employer, experience level, and location data across any combination of region, industry, and employment type. The get_vacancy endpoint returns the full job description, key skills array, and employer details for a specific listing by ID.
Search Vacancies
The search_vacancies endpoint accepts keyword queries via the text parameter alongside a range of structured filters. The area parameter accepts region IDs — for example, 1 for Moscow and 2 for St. Petersburg — and supports multiple values for broader geographic coverage. Results can be sorted by relevance, publication_time, salary_desc, or salary_asc using the order_by parameter. Each vacancy object in the response includes id, name, salary, experience, employer, address, and labels (such as remote work indicators). Pagination is handled via the zero-indexed page parameter; the response includes found (total matching vacancies), pages, and per_page to navigate result sets.
Vacancy Detail
The get_vacancy endpoint takes a single vacancy_id (obtained from search results) and returns the full listing. This includes the complete HTML description field, a key_skills array listing required competencies, structured employer data with ID and name, salary text, experience requirement, and a direct url back to the listing on hh.ru. The labels field surfaces work-format tags such as remote eligibility.
Filtering and Coverage
The salary and currency parameters let you filter vacancies by minimum compensation in a specific currency, including RUB, USD, EUR, and several CIS currencies (KZT, UAH, UZS, GEL, KGS, AZN, BYR). The industry parameter accepts numeric industry IDs for sector-specific queries. The label filter supports values like not_from_agency, accredited_it, and accept_handicapped, enabling precise candidate-facing or compliance-related searches.
- Aggregate Moscow and St. Petersburg tech job listings filtered by salary and the
accredited_itlabel for IT sector analysis - Track new vacancy publications in a specific industry by polling
search_vacanciessorted bypublication_time - Extract
key_skillsarrays fromget_vacancyresponses to identify in-demand competencies across a job category - Build a salary benchmarking dataset by querying
search_vacancieswithorder_by=salary_descacross multiple regions - Monitor a specific employer's active listings by searching on company name and collecting vacancy IDs for detail retrieval
- Compile full job descriptions via
get_vacancyto power a searchable internal jobs database or career recommendation tool
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does hh.ru have an official developer API?+
What does `search_vacancies` return and how granular is the salary data?+
vacancies array includes a salary field returned as a text string (e.g. '100 000–150 000 RUR'). The endpoint lets you filter by a minimum salary integer and a currency code, but the salary in each result is a display string rather than structured min/max integers. The get_vacancy endpoint similarly returns salary as a text field.Does the API return resume or candidate profile data?+
Are there pagination limits on search results?+
search_vacancies response includes pages, per_page, and found fields so you can iterate through result sets. hh.ru's search interface caps deep pagination — results beyond a certain page depth may not be accessible, which means very large result sets (thousands of pages) may be truncated in practice. Applying tighter filters like area, industry, or salary reduces result set size and improves coverage.Can I retrieve employer company profiles or company-level metadata beyond what's in a vacancy?+
id and name fields embedded in each vacancy. Standalone company profiles, employee counts, or employer ratings are not covered. You can fork this API on Parse and revise it to add an endpoint for employer detail pages.