{ "openapi": "3.0.1", "info": { "title": "HH.kz Job Scraper — Vacancies, Salaries & Employers", "description": "hh.kz (HeadHunter Kazakhstan) vacancies for recruiters, salary benchmarking, B2B lead-gen and AI agents: all site filters (city, role, industry, employer, experience, schedule, format, salary), salary range, employer, address, optional full vacancy text and skills.", "version": "0.1", "x-build-id": "NL5NKQUx2valn3Ftp" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/yadroo~hh-kz-vacancies/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-yadroo-hh-kz-vacancies", "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/yadroo~hh-kz-vacancies/runs": { "post": { "operationId": "runs-sync-yadroo-hh-kz-vacancies", "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/yadroo~hh-kz-vacancies/run-sync": { "post": { "operationId": "run-sync-yadroo-hh-kz-vacancies", "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": { "query": { "title": "Search query", "type": "string", "description": "Keywords as typed into the hh search box. Supports hh query language: quotes for exact phrase (\"1С бухгалтер\"), OR, NOT, `!word` for exact word form. Leave empty to list all vacancies of an employer or professional role." }, "site": { "title": "Site", "enum": [ "hh.kz", "hh.ru", "hh.uz" ], "type": "string", "description": "HeadHunter site to search. Vacancies are shared across hh sites; the site mostly decides the default area and currency display.", "default": "hh.kz" }, "area": { "title": "Area (city / region)", "type": "string", "description": "hh area id, Russian name or latin slug; several separated by commas. Empty = the whole country of the chosen site (hh.kz → Kazakhstan 40, hh.ru → Russia 113, hh.uz → Uzbekistan 97). Examples: 160 Almaty, 159 Astana, 205 Shymkent, 177 Karaganda, \"almaty\", \"Астана\", \"160,159\". An unknown name stops the run with a hint (never a wider search). All 217 Kazakhstan areas: README → Reference." }, "searchFields": { "title": "Search in", "type": "array", "description": "Where the keywords must match. Empty = everywhere (title, company name, description). Choose only \"name\" for precise title matches.", "items": { "type": "string", "enum": [ "name", "company_name", "description" ], "enumTitles": [ "в названии вакансии (name)", "в названии компании (company_name)", "в описании вакансии (description)" ] } }, "excludeWords": { "title": "Exclude words", "type": "array", "description": "Vacancies containing any of these words are excluded server-side (hh `excluded_text`), e.g. [\"стажер\", \"junior\"].", "items": { "type": "string" } }, "professionalRoles": { "title": "Professional roles", "type": "array", "description": "hh professional role ids or exact Russian names, e.g. \"96\" (Программист, разработчик), \"18\" (Бухгалтер), \"70\" (Менеджер по продажам). An unknown name stops the run with a \"did you mean\" hint. Full list of 304 roles in 27 categories: README → Reference.", "items": { "type": "string" } }, "industry": { "title": "Employer industries", "type": "array", "description": "hh industry ids: top-level (7 = IT, 43 = Finance, 29 = Agriculture, 47 = Oil & gas…) or sub-industry like \"7.540\". A value that is not an id stops the run with a hint. List in README → Reference.", "items": { "type": "string" } }, "employerId": { "title": "Employer id", "type": "string", "description": "Only vacancies of this company — the number in https://hh.kz/employer/ (also in this actor's `employer.id` output). Good for competitor hiring monitoring." }, "experience": { "title": "Experience", "enum": [ "", "noExperience", "between1And3", "between3And6", "moreThan6" ], "type": "string", "description": "Required work experience (hh `experience`): one level. Values outside the list are refused by Apify before the run.", "default": "" }, "employment": { "title": "Employment type", "type": "array", "description": "hh `employment`: full, part, project, volunteer, probation (internship). Several = OR.", "items": { "type": "string", "enum": [ "full", "part", "project", "volunteer", "probation" ], "enumTitles": [ "Полная занятость (full)", "Частичная занятость (part)", "Проектная работа (project)", "Волонтерство (volunteer)", "Стажировка (probation)" ] } }, "schedule": { "title": "Schedule", "type": "array", "description": "hh `schedule`: fullDay, shift, flexible, remote, flyInFlyOut (rotation). Several = OR.", "items": { "type": "string", "enum": [ "fullDay", "shift", "flexible", "remote", "flyInFlyOut" ], "enumTitles": [ "Полный день (fullDay)", "Сменный график (shift)", "Гибкий график (flexible)", "Удаленная работа (remote)", "Вахтовый метод (flyInFlyOut)" ] } }, "workFormat": { "title": "Work format", "type": "array", "description": "hh `work_format` (newer filter): ON_SITE, REMOTE, HYBRID, FIELD_WORK.", "items": { "type": "string", "enum": [ "ON_SITE", "REMOTE", "HYBRID", "FIELD_WORK" ], "enumTitles": [ "На месте работодателя (ON_SITE)", "Удалённо (REMOTE)", "Гибрид (HYBRID)", "Разъездной (FIELD_WORK)" ] } }, "partTime": { "title": "Part-time options", "type": "array", "description": "hh `part_time`: project work, part-time, temporary, 4–6 hour shifts, weekends only, evenings.", "items": { "type": "string", "enum": [ "employment_project", "employment_part", "temporary_job_true", "from_four_to_six_hours_in_a_day", "only_saturday_and_sunday", "start_after_sixteen" ], "enumTitles": [ "Project work (employment_project)", "Part-time employment (employment_part)", "Temporary job (temporary_job_true)", "Shifts of 4-6 hours a day (from_four_to_six_hours_in_a_day)", "Saturdays and Sundays only (only_saturday_and_sunday)", "Day starts after 16:00 (start_after_sixteen)" ] } }, "labels": { "title": "Labels", "type": "array", "description": "hh `label` flags, e.g. not_from_agency (exclude recruiting agencies), with_address, accredited_it, low_performance (<10 responses — less competition).", "items": { "type": "string", "enum": [ "with_address", "accept_handicapped", "not_from_agency", "accept_kids", "accredited_it", "low_performance", "internship", "night_shifts", "with_salary", "accept_teens", "accept_labor_contract" ], "enumTitles": [ "Только с адресом (with_address)", "Только доступные для людей с инвалидностью (accept_handicapped)", "Без вакансий агентств (not_from_agency)", "Только доступные для соискателей от 14 лет (accept_kids)", "Только аккредитованные ИТ-компании (accredited_it)", "Только вакансии, у которых меньше 10 откликов (low_performance)", "Стажировка (internship)", "Вечерние или ночные смены (night_shifts)", "Указан доход (with_salary)", "Только доступные для соискателей от 16 лет (accept_teens)", "Трудовой договор (accept_labor_contract)" ] } }, "salaryFrom": { "title": "Salary at least", "minimum": 0, "type": "integer", "description": "Vacancies whose salary range includes this amount (hh `salary`), in `currency`. Combine with `onlyWithSalary` to drop vacancies without a salary." }, "currency": { "title": "Salary currency", "enum": [ "AZN", "BYR", "EUR", "GEL", "KGS", "KZT", "RUR", "UAH", "USD", "UZS" ], "type": "string", "description": "Currency of `salaryFrom` (hh converts internally). KZT, USD, EUR are in active use on hh.kz; Russian rubles are `RUR`, as hh writes them. Values outside the list are refused by Apify before the run.", "default": "KZT" }, "onlyWithSalary": { "title": "Only with salary", "type": "boolean", "description": "Skip vacancies that do not state a salary.", "default": false }, "period": { "title": "Published within", "enum": [ "", "1", "3", "7", "30" ], "type": "string", "description": "Server-side publication period (hh `search_period`). For finer control use `sinceHours`.", "default": "" }, "sinceHours": { "title": "Published in the last N hours", "minimum": 1, "type": "integer", "description": "Keep only vacancies published (or bumped) within N hours. Sets sort to publication_time and stops paging at the first older vacancy — cheap hourly monitoring." }, "sort": { "title": "Sort", "enum": [ "publication_time", "salary_desc", "salary_asc", "relevance" ], "type": "string", "description": "hh `order_by`.", "default": "relevance" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Stop after this many vacancies. hh returns 100 per page and never more than 2000 per search — split by area or role to go further. The run also stops at your max cost per run.", "default": 50 }, "maxPages": { "title": "Max pages", "minimum": 1, "maximum": 20, "type": "integer", "description": "Safety cap on search pages (100 vacancies each).", "default": 20 }, "detail": { "title": "Open vacancy pages", "type": "boolean", "description": "Open each vacancy page and add full description, key skills, professional roles, archive status and coordinates; contacts only when hh puts them on the page (rare: hh now loads them after a click). +1 request per vacancy at a polite pace: about 23 vacancies a minute, ~1,300 in the default 1-hour timeout (rows are saved as they are ready; raise the timeout for more).", "default": false }, "dedupe": { "title": "Deduplicate", "type": "boolean", "description": "Skip vacancy ids already seen in this run.", "default": true }, "fields": { "title": "Output fields", "type": "array", "description": "Keep only these fields, in this order, e.g. [\"title\", \"employer\", \"salaryFrom\", \"salaryTo\", \"areaName\"]. `id`, `url` and (when a vacancy page failed) `detailError` are always kept. Empty = every field. Names: README → Output; case and spaces are forgiven, an unknown name is skipped with a hint.", "items": { "type": "string" } } } }, "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 }, "PROXY_UNBLOCKER_UNITS": { "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 }, "PROXY_UNBLOCKER_UNITS": { "type": "integer", "example": 0 } } } } } } } } } }