# HeadHunter Jobs Scraper (`automation-lab/headhunter-jobs-scraper`) Actor Scrape public hh.ru vacancies by keyword or search URL. Extract employers, locations, salary text, parsed salary ranges, and descriptions. - **URL**: https://apify.com/automation-lab/headhunter-jobs-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Jobs, Lead generation - **Stats:** 2 total users, 1 monthly users, 66.7% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## HeadHunter Jobs Scraper Scrape public hh.ru vacancy search results and detail pages. Get clean vacancy titles, employers, salary text, parsed salary ranges, locations, experience, employment, schedules, descriptions, source URLs, and timestamps from HeadHunter / hh.ru. ### What does HeadHunter Jobs Scraper do? HeadHunter Jobs Scraper extracts public job vacancy data from hh.ru search pages. It is built for public vacancy pages that are visible without logging in. The actor starts from either: - a search keyword plus hh.ru area id, or - a complete hh.ru search URL copied from the browser. It then paginates result pages, normalizes vacancy URLs, optionally visits vacancy detail pages, and saves structured records to the default dataset. ### Who is it for? Recruiting teams use it to monitor public openings by skill, city, or employer. Sourcing agencies use it to build lead lists for outreach and market mapping. Job-board analysts use it to track job demand, salary language, and hiring trends. Labor-market researchers use it to collect comparable public vacancy data. Sales teams use it to identify companies currently hiring for specific roles. ### Why use this actor? - ✅ Scrapes public hh.ru HTML without relying on the blocked JSON API - ✅ Supports keyword and direct search URL workflows - ✅ Extracts both search-card data and optional vacancy detail fields - ✅ Normalizes vacancy IDs and vacancy URLs where possible - ✅ Adds salary range parsing when the salary text is parseable - ✅ Keeps provenance fields for reproducible analysis - ✅ Uses HTTP + Cheerio for low compute cost ### Data you can extract | Field | Description | | --- | --- | | `title` | Vacancy title | | `vacancyId` | hh.ru vacancy id when detected | | `url` | Normalized vacancy URL | | `employer` | Employer name | | `employerUrl` | Employer profile URL | | `location` | Location or address text | | `salaryText` | Raw public salary text | | `salaryFrom` | Parsed lower salary bound | | `salaryTo` | Parsed upper salary bound | | `salaryCurrency` | Parsed currency code | | `experience` | Experience requirement | | `schedule` | Schedule text from the detail page | | `employment` | Employment type text from the detail page | | `publishedAtText` | Public publication/update text when available | | `snippet` | Search-result snippet when available | | `description` | Vacancy description from the detail page | | `sourceSearchUrl` | Search page that produced the record | | `scrapedAt` | ISO timestamp when the record was saved | ### How much does it cost to scrape hh.ru jobs? The actor uses pay-per-event pricing. There is a small run-start charge and a per-vacancy charge for each saved result. Formula-based cloud validation set the BRONZE per-vacancy price at about $0.082 per 1,000 saved vacancy records, plus a $0.005 run-start event. Always keep first test runs small. Recommended first run: - `searchQuery`: `python` - `area`: `1` - `maxItems`: `25` - `maxPages`: `3` - `includeDetails`: `true` ### Input options #### Search query Use `searchQuery` when you want the actor to build the hh.ru search URL for you. Example: ```json "python" ```` #### Area / region ID Use `area` for the hh.ru region id. Common examples: - `1` — Moscow - `2` — Saint Petersburg - `113` — Russia #### Search URL Use `searchUrl` when you already configured filters in hh.ru and copied the browser URL. When `searchUrl` is set, it overrides `searchQuery` and `area`. Example: ```json "https://hh.ru/search/vacancy?text=python&area=1" ``` #### Maximum vacancies Use `maxItems` to stop after a specific number of vacancy records. #### Maximum pages Use `maxPages` to limit pagination. Each hh.ru search page usually contains about 20 vacancies. #### Include vacancy details Set `includeDetails` to `true` to visit each vacancy detail page and enrich the output. Set it to `false` for faster search-list-only scraping. #### Request delay Use `requestDelayMs` to slow down requests. A polite default delay is included. ### Example input ```json { "searchQuery": "python", "area": "1", "maxItems": 25, "maxPages": 3, "includeDetails": true, "requestDelayMs": 750 } ``` ### Example with a copied search URL ```json { "searchUrl": "https://hh.ru/search/vacancy?text=data%20analyst&area=1", "maxItems": 50, "maxPages": 5, "includeDetails": true } ``` ### Output example ```json { "title": "Python Developer", "vacancyId": "123456789", "url": "https://hh.ru/vacancy/123456789", "employer": "Example Company", "employerUrl": "https://hh.ru/employer/12345", "location": "Москва", "salaryText": "от 150 000 ₽ за месяц", "salaryFrom": 150000, "salaryTo": null, "salaryCurrency": "RUB", "experience": "1–3 года", "schedule": "График: 5/2", "employment": "Полная занятость", "publishedAtText": "", "snippet": null, "description": "Public vacancy description text...", "sourceSearchUrl": "https://hh.ru/search/vacancy?text=python&area=1&page=0", "scrapedAt": "2026-06-02T00:00:00.000Z" } ``` ### How to run 1. Open the actor on Apify. 2. Enter a search keyword or paste a hh.ru search URL. 3. Choose the area id and maximum vacancies. 4. Keep `includeDetails` enabled if you need descriptions. 5. Start the run. 6. Export the dataset as JSON, CSV, Excel, or via API. ### Tips for best results - Start with 25–50 vacancies to validate your filters. - Use copied hh.ru URLs for advanced filters. - Increase `requestDelayMs` if responses slow down. - Disable `includeDetails` when you only need result-list fields. - Use `sourceSearchUrl` to audit which search page produced each record. ### Integrations Use this actor in recruiting dashboards, lead scoring systems, BI pipelines, and market intelligence workflows. Typical workflows: - Send dataset items to Google Sheets for recruiter review. - Load CSV exports into Airtable or Notion. - Use the Apify API to refresh labor-market dashboards daily. - Combine vacancy records with company enrichment actors. - Trigger alerts when new jobs match a keyword and city. ### API usage with Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/headhunter-jobs-scraper').call({ searchQuery: 'python', area: '1', maxItems: 25, includeDetails: true, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` ### API usage with Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('automation-lab/headhunter-jobs-scraper').call(run_input={ 'searchQuery': 'python', 'area': '1', 'maxItems': 25, 'includeDetails': True, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ``` ### API usage with cURL ```bash curl -X POST "https://api.apify.com/v2/acts/automation-lab~headhunter-jobs-scraper/runs?token=$APIFY_TOKEN" \ -H "Content-Type: application/json" \ -d '{"searchQuery":"python","area":"1","maxItems":25,"includeDetails":true}' ``` ### MCP usage Use the actor through Apify MCP in Claude Code or Claude Desktop. MCP URL: ```text https://mcp.apify.com/?tools=automation-lab/headhunter-jobs-scraper ``` Add it in Claude Code: ```bash claude mcp add apify-headhunter-jobs "https://mcp.apify.com/?tools=automation-lab/headhunter-jobs-scraper" ``` Claude Desktop JSON config example: ```json { "mcpServers": { "apify-headhunter-jobs": { "url": "https://mcp.apify.com/?tools=automation-lab/headhunter-jobs-scraper" } } } ``` Example prompts: - "Run the HeadHunter Jobs Scraper for Python jobs in Moscow and summarize salary ranges." - "Find 50 public hh.ru data analyst vacancies and group them by employer." - "Scrape this hh.ru search URL and export the dataset as CSV." ### Reliability notes This actor intentionally uses the public HTML pages. The hh.ru JSON API returned 403 in feasibility checks, so the actor does not depend on it. Selectors may change when hh.ru redesigns its frontend. If a page returns no public vacancy cards, the actor stops gracefully. ### Limits The actor only scrapes public data visible without an account. It does not apply for jobs, contact candidates, log in, or bypass access controls. Some advertised or redirect result links may be normalized from the vacancy id detected in the card. Salary parsing is best-effort because salary formats vary by employer and country. ### Legality This actor extracts publicly available job vacancy information. Make sure your use complies with applicable laws, hh.ru terms, and privacy requirements. Do not scrape personal data unnecessarily. Do not use the output for spam or prohibited employment decisions. ### FAQ #### Does this actor require a HeadHunter account? No. It is designed for vacancy data visible without logging in. #### Why did my run return fewer items than requested? The search may have fewer public results, hh.ru may return duplicate vacancies across pages, or your `maxPages` limit may be too low. #### Why is salary sometimes empty? Many employers do not publish salary information. The actor saves salary fields only when public salary text is present. #### Should I use `searchQuery` or `searchUrl`? Use `searchQuery` for simple searches. Use `searchUrl` for advanced hh.ru filters copied from the browser. ### Related scrapers Explore other Automation Lab actors for job boards, company enrichment, search results, and lead generation: - https://apify.com/automation-lab/google-search-scraper - https://apify.com/automation-lab/google-maps-scraper - https://apify.com/automation-lab/trustpilot-scraper ### Support If the actor stops returning expected results, provide the input JSON, run URL, and a public hh.ru sample URL. We can then compare the current HTML structure with the extractor selectors. # Actor input Schema ## `searchQuery` (type: `string`): Keyword or phrase to search on hh.ru, for example python, data analyst, or product manager. Ignored when Search URL is provided. ## `area` (type: `string`): hh.ru area id. Examples: 1 = Moscow, 2 = Saint Petersburg, 113 = Russia. Ignored when Search URL is provided. ## `searchUrl` (type: `string`): Full hh.ru /search/vacancy URL with filters. If set, this overrides Search query and Area. ## `maxItems` (type: `integer`): Maximum number of vacancy records to save. ## `maxPages` (type: `integer`): Maximum number of hh.ru search result pages to scan. Each page usually contains about 20 vacancies. ## `includeDetails` (type: `boolean`): Fetch each vacancy detail page to enrich salary, description, employment, schedule, and other fields. Disable for faster result-list-only scraping. ## `requestDelayMs` (type: `integer`): Polite delay between HTTP requests. Increase if hh.ru responds slowly. ## Actor input object example ```json { "searchQuery": "python", "area": "1", "searchUrl": "https://hh.ru/search/vacancy?text=python&area=1", "maxItems": 10, "maxPages": 3, "includeDetails": true, "requestDelayMs": 500 } ``` # Actor output Schema ## `overview` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "searchQuery": "python", "area": "1", "searchUrl": "https://hh.ru/search/vacancy?text=python&area=1", "maxItems": 10, "maxPages": 3, "includeDetails": true, "requestDelayMs": 500 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/headhunter-jobs-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "searchQuery": "python", "area": "1", "searchUrl": "https://hh.ru/search/vacancy?text=python&area=1", "maxItems": 10, "maxPages": 3, "includeDetails": True, "requestDelayMs": 500, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/headhunter-jobs-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "searchQuery": "python", "area": "1", "searchUrl": "https://hh.ru/search/vacancy?text=python&area=1", "maxItems": 10, "maxPages": 3, "includeDetails": true, "requestDelayMs": 500 }' | apify call automation-lab/headhunter-jobs-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/headhunter-jobs-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "HeadHunter Jobs Scraper", "description": "Scrape public hh.ru vacancies by keyword or search URL. Extract employers, locations, salary text, parsed salary ranges, and descriptions.", "version": "0.1", "x-build-id": "gmbGLSmw7Tq4og6zS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~headhunter-jobs-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-headhunter-jobs-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/automation-lab~headhunter-jobs-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-headhunter-jobs-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/automation-lab~headhunter-jobs-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-headhunter-jobs-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "searchQuery": { "title": "Search query", "type": "string", "description": "Keyword or phrase to search on hh.ru, for example python, data analyst, or product manager. Ignored when Search URL is provided.", "default": "python" }, "area": { "title": "Area / region ID", "type": "string", "description": "hh.ru area id. Examples: 1 = Moscow, 2 = Saint Petersburg, 113 = Russia. Ignored when Search URL is provided.", "default": "1" }, "searchUrl": { "title": "Search URL (optional)", "type": "string", "description": "Full hh.ru /search/vacancy URL with filters. If set, this overrides Search query and Area." }, "maxItems": { "title": "Maximum vacancies", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum number of vacancy records to save.", "default": 10 }, "maxPages": { "title": "Maximum search pages", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum number of hh.ru search result pages to scan. Each page usually contains about 20 vacancies.", "default": 3 }, "includeDetails": { "title": "Include vacancy details", "type": "boolean", "description": "Fetch each vacancy detail page to enrich salary, description, employment, schedule, and other fields. Disable for faster result-list-only scraping.", "default": true }, "requestDelayMs": { "title": "Delay between requests (ms)", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Polite delay between HTTP requests. Increase if hh.ru responds slowly.", "default": 500 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```