hh APIhh.ru ↗
Search hh.ru job vacancies by salary, region, experience, and industry. Retrieve full job details including skills, employer info, and HTML descriptions.
What is the hh 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 accepts filters for region, salary, experience level, employment type, and industry, returning paginated result sets. The get_vacancy endpoint returns full vacancy details including key skills, employer data, and the complete HTML job description across 15+ fields per record.
curl -X GET 'https://api.parse.bot/scraper/3ccf546c-1803-406c-902c-9e3df9fe872e/search_vacancies?area=1&text=python+developer' \ -H 'X-API-Key: $PARSE_API_KEY'
Full-text search over hh.ru vacancies with filters for region, experience, employment type, schedule, salary, and more. Returns paginated results. Each vacancy includes id, title, salary, employer, address, experience, and labels. Pagination is page-based (0-indexed). The total matched count is in `found`; `pages` gives total pages available.
| 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 summary objects with id, name, url, salary, experience, experience_id, employer, address, labels"
},
"sample": {
"data": {
"page": 0,
"found": 3210,
"pages": 3,
"per_page": 5,
"vacancies": [
{
"id": "133820538",
"url": "https://hh.ru/vacancy/133820538",
"name": "Middle Backend PHP Developer",
"labels": [
"Можно удалённо"
],
"salary": null,
"address": "Санкт-Петербург",
"employer": {
"id": "11315084",
"name": "ОООИзигейт"
},
"experience": "Опыт 3-6 лет",
"experience_id": "between3And6"
}
]
},
"status": "success"
}
}About the hh API
Search Vacancies
The search_vacancies endpoint runs a full-text search across hh.ru listings and returns paginated summaries. The text parameter accepts free-form keywords such as python developer or data engineer. Results can be narrowed by area (region ID, where 1 = Moscow and 2 = St. Petersburg, with multiple values supported), salary (minimum amount with a paired currency code from RUR, USD, EUR, KZT, and others), industry (numeric ID), and label (flags such as not_from_agency, accept_handicapped, or accredited_it). Sorting is controlled by order_by with options: relevance, publication_time, salary_desc, and salary_asc. Each response includes pagination metadata — page, pages, found, and per_page — alongside an array of vacancy summary objects containing id, name, salary, employer, address, experience, and labels.
Vacancy Detail
The get_vacancy endpoint accepts a numeric vacancy_id obtained from search_vacancies results and returns the full listing record. Key fields include key_skills (array of skill strings), description (full HTML job description), experience (human-readable requirement text), employer (object with id and name), salary, address, and labels. This is the endpoint to use when you need the complete posting content rather than the summary fields available from search.
Coverage and Pagination
Pagination in search_vacancies is 0-indexed via the page parameter. The found field reports the total number of matching vacancies, and pages tells you how many pages are available at the current per_page size. hh.ru covers job listings primarily from Russia and CIS countries; region filtering is ID-based, so callers targeting specific geographies need to know the corresponding numeric area IDs.
The hh API is a managed, monitored endpoint for hh.ru — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when hh.ru changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official hh.ru API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Aggregate software engineering job postings from Moscow and St. Petersburg filtered by minimum salary in RUR
- Monitor new vacancies in a specific industry by polling
search_vacanciessorted bypublication_time - Extract
key_skillsarrays across many vacancies to identify the most in-demand technical skills on the Russian job market - Build a job alert system that checks
foundcounts for a given keyword and notifies users when new postings appear - Populate a recruiter dashboard with employer names, addresses, and experience requirements from vacancy summaries
- Filter listings to only agency-free postings using the
not_from_agencylabel parameter - Compare salary ranges across industries by searching with different
industryIDs and collectingsalaryfields
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. 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 `get_vacancy` return that `search_vacancies` does not?+
search_vacancies returns summary fields: id, name, salary, employer, address, experience, and labels. get_vacancy adds the full HTML description, the key_skills array, and the vacancy url. If you need the actual job description text or required skills, you need to call get_vacancy with the id from the search results.Are there limitations on how many results `search_vacancies` can return?+
found, pages, and per_page so you can iterate through pages. hh.ru enforces its own caps on deep pagination — typically results beyond a few thousand are not accessible regardless of the page parameter, which mirrors the behavior of the source site's own search interface.Does the API cover resume or applicant profile data?+
search_vacancies and vacancy detail retrieval via get_vacancy. Resume profiles, applicant data, and employer company pages are not exposed. You can fork this API on Parse and revise it to add an endpoint covering those data types.Can I filter vacancies by employment schedule or work format?+
search_vacancies endpoint exposes label values such as accredited_it and not_from_agency for categorical filtering, but granular schedule types (e.g., remote-only, full-day, shift) are not currently a dedicated filter parameter in the API. The vacancy summary and detail objects do include labels fields that may reflect some format tags. You can fork this API on Parse and revise it to add schedule-specific filter parameters.