# VK Groups Scraper (`khadinakbar/vk-groups-scraper`) Actor Scrape public VK (VKontakte) groups by URL, handle, ID, or keyword. Use for CIS social research and community lead mapping. Not for members, posts, private groups, or user profiles. Returns name, URL, members, activity, links, avatar, source. $0.0055/group + $0.00005 start. - **URL**: https://apify.com/khadinakbar/vk-groups-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** Social media, Lead generation, MCP servers - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $5.50 / 1,000 vk group scrapeds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## VK Groups Scraper Scrape public **VK (VKontakte) groups and communities** by URL, handle, numeric group ID, or keyword search. The actor returns one clean JSON row per community with its name, VK URL, public member count, activity/category, website, city/country, avatar, verification/access status, source input, and scrape timestamp. ### When To Use It Use this actor when you need a structured list of VK communities for CIS market research, social listening, lead mapping, competitor monitoring, or community discovery. Do not use it for VK member lists, wall posts, videos, private groups, user profiles, login-only content, or messages. This actor does not bypass authentication and does not collect private member data. ### Output One record represents one public VK group or community. | Field | Description | |---|---| | `groupId`, `screenName`, `groupUrl` | VK identifiers and canonical community URL | | `name`, `description`, `status`, `activity`, `type` | Public identity and category/profile text | | `membersCount` | Public member/follower/subscriber count when exposed | | `isClosed`, `accessStatus`, `isVerified` | Public access and verification signals | | `photoUrl`, `coverUrl`, `website` | Public media and website links | | `city`, `country`, `contacts`, `links` | API-exposed public profile details when available | | `sourceInput`, `sourceType`, `sourceRoute`, `searchQuery` | Provenance for API/MCP workflows | | `scrapedAt` | ISO timestamp for freshness | ```json { "groupId": 22822305, "screenName": "vk", "groupUrl": "https://vk.com/vk", "name": "ВКонтакте", "description": "Это главное сообщество Команды ВКонтакте.", "activity": null, "type": null, "isClosed": true, "accessStatus": "login_required_preview", "isVerified": true, "membersCount": 14100000, "photoUrl": "http://sun9-8.userapi.com/example.jpg", "website": null, "sourceInput": "vk", "sourceType": "target", "sourceRoute": "browser-profile", "searchQuery": null, "scrapedAt": "2026-07-15T12:00:00.000Z" } ```` ### Pricing **Pay per event + usage:** **$0.0055 per group record** + a **$0.00005 actor-start fee**. A 50-group run has at most **$0.275** in group event charges. Skipped, invalid, blocked, or duplicate targets are not billed as group rows. Apify compute and proxy usage are passed through separately. ### Input | Field | Required | Description | |---|---:|---| | `targets` | no | Known VK community handles, URLs, numeric IDs, `club123`, `public123`, or `-123` owner IDs | | `searchQueries` | no | Keywords for discovering communities; best with `vkAccessToken`, browser fallback is best effort | | `maxGroups` | no | Total billable group cap across all targets and searches | | `maxGroupsPerSearch` | no | Per-keyword cap before moving to the next search query | | `vkAccessToken` | no | Optional VK API token for structured `groups.getById` and `groups.search` routes | | `proxyCountry` | no | Residential proxy country, default `RU` | | `includeRawData` | no | Include raw VK API group object for debugging | | `saveHtmlSnapshot` | no | Save public VK HTML snapshots to the key-value store for troubleshooting | #### Direct Targets ```json { "targets": ["vk", "https://vk.com/vkvideo", "club1"], "maxGroups": 25 } ``` #### Keyword Search With VK API Token ```json { "searchQueries": ["gaming", "маркетинг"], "vkAccessToken": "", "maxGroups": 50, "maxGroupsPerSearch": 25 } ``` ### How It Works 1. **VK API route:** When `vkAccessToken` is supplied, the actor uses `groups.getById` for direct targets and `groups.search` for keyword discovery. This is the most structured and reliable route. 2. **Tokenless public routes:** Without a token, the actor first tries mobile public HTML over Apify Residential proxy. If VK serves a shell or challenge, it falls back to Camoufox and parses the unauthenticated public preview when VK exposes one. Keyword search without a token uses VK public search as a best-effort fallback. Both routes normalize into the same dataset schema, so you can start tokenless and add a token later without changing downstream code. ### Reliability Notes VK has aggressive IP reputation and login/redirect challenges. Tokenless mode works best for small, public community lookups over a CIS Residential proxy. If VK challenges every route and zero useful records are saved, the run fails honestly as `UPSTREAM_FAILED`; if some groups are saved and others fail, the run finishes as `PARTIAL`. For dependable high-volume keyword discovery and exact group metadata, use a VK API token. The actor never asks for a VK password or cookie. Every run writes: - `OUTPUT` — compact terminal outcome, result count, charge count, warnings, and dataset ID. - `RUN_SUMMARY` — route attempts, skipped inputs, validation errors, cost-cap state, storage IDs, billing counters, and timestamps. ### MCP / AI Agents Use this actor when an agent needs public VK community metadata from known handles/URLs or keyword discovery. It returns one flat record per group with stable keys and provenance fields. It is not the right tool for VK posts, private communities, user profiles, member extraction, or login-only data. ### Legal Use this actor only for publicly accessible data and in compliance with VK's Terms of Service, applicable laws, and data-protection regulations. You are responsible for how you collect and use the data. Do not use it to scrape private content, collect members from closed groups, or harm individuals. # Actor input Schema ## `targets` (type: `array`): Use this when you already know the VK community URL, handle, or numeric group ID. Accepts values such as 'vk', 'https://vk.com/vkvideo', 'club1', 'public1', or '-1'. Defaults to \['vk'] only when no targets or search queries are supplied. Not for VK user profiles, member lists, wall posts, or video URLs. ## `searchQueries` (type: `array`): Use this when you want to discover VK communities by keyword. Enter one phrase per line, for example 'gaming' or 'маркетинг'. Defaults to an empty list; with vkAccessToken the Actor uses VK groups.search, otherwise it tries public web search. Not a place for VK URLs; put known communities in targets. ## `maxGroups` (type: `integer`): Use this to cap the total number of billable group records saved across targets and searches. Example: 50 returns at most 50 group rows. Defaults to 50 and is clamped to 1-1000 at runtime. Not a page count; each saved VK group is one billable event. ## `maxGroupsPerSearch` (type: `integer`): Use this to limit how many communities each keyword can add before the Actor moves to the next search query. Example: 25 keeps broad terms from consuming the whole run. Defaults to 25 and is clamped to maxGroups and 250. Not used for direct targets. ## `vkAccessToken` (type: `string`): Use this when you have a VK API service or user access token and want structured API results, especially for keyword search. Paste only the token string, for example one generated from a VK app at dev.vk.com. Defaults to blank, which uses public tokenless browsing where possible. Not your VK password, login cookie, or private account session. ## `proxyCountry` (type: `string`): Use this to choose the Residential proxy country used to reach VK. Example: 'RU' is recommended because VK often throttles datacenter and non-CIS routes. Defaults to RU. Not a content-language filter; it only controls network egress. ## `includeRawData` (type: `boolean`): Use this when you need the raw VK API group object for debugging or custom downstream parsing. Defaults to false for smaller, cleaner exports. Browser-route rows include only a small raw diagnostic object because VK HTML is too large for normal datasets. Not needed for spreadsheet exports or MCP clients. ## `saveHtmlSnapshot` (type: `boolean`): Use this when troubleshooting VK public-page markup or a suspected selector drift. Example: true writes DEBUG\_GROUP\_DOM and DEBUG\_GROUP\_SEARCH records to the key-value store. Defaults to false for normal runs. Not needed when vkAccessToken is supplied and the API route succeeds. ## `proxyConfiguration` (type: `object`): Use this only when you need to override the default Apify Residential proxy. Example: keep the default Residential proxy unless you have a tested VK route. Defaults to Apify Residential in proxyCountry. Not required for normal runs; weak proxies can lower VK reliability. ## Actor input object example ```json { "targets": [ "vk", "https://vk.com/vkvideo", "club1" ], "searchQueries": [ "gaming", "music" ], "maxGroups": 50, "maxGroupsPerSearch": 25, "proxyCountry": "RU", "includeRawData": false, "saveHtmlSnapshot": false, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `dataset` (type: `string`): One normalized VK group or community per row with identity, public member count, activity, links, provenance, and scrape timestamp. ## `datasetCsv` (type: `string`): CSV export of the normalized VK group dataset. ## `runSummary` (type: `string`): Detailed counters, route attempts, skipped inputs, billing counts, warnings, timestamps, and terminal outcome. ## `outputSummary` (type: `string`): Compact agent-friendly outcome, result count, charge count, warnings, and dataset ID. # 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 = { "targets": [ "vk", "vkvideo", "kinopoisk" ], "searchQueries": [ "gaming", "music" ], "maxGroups": 50, "maxGroupsPerSearch": 25 }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/vk-groups-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 = { "targets": [ "vk", "vkvideo", "kinopoisk", ], "searchQueries": [ "gaming", "music", ], "maxGroups": 50, "maxGroupsPerSearch": 25, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/vk-groups-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 '{ "targets": [ "vk", "vkvideo", "kinopoisk" ], "searchQueries": [ "gaming", "music" ], "maxGroups": 50, "maxGroupsPerSearch": 25 }' | apify call khadinakbar/vk-groups-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/vk-groups-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "VK Groups Scraper", "description": "Scrape public VK (VKontakte) groups by URL, handle, ID, or keyword. Use for CIS social research and community lead mapping. Not for members, posts, private groups, or user profiles. Returns name, URL, members, activity, links, avatar, source. $0.0055/group + $0.00005 start.", "version": "1.0", "x-build-id": "c9wPUzxzjxJvy1fEc" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~vk-groups-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-vk-groups-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/khadinakbar~vk-groups-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-vk-groups-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/khadinakbar~vk-groups-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-vk-groups-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": { "targets": { "title": "VK group targets", "type": "array", "description": "Use this when you already know the VK community URL, handle, or numeric group ID. Accepts values such as 'vk', 'https://vk.com/vkvideo', 'club1', 'public1', or '-1'. Defaults to ['vk'] only when no targets or search queries are supplied. Not for VK user profiles, member lists, wall posts, or video URLs.", "items": { "type": "string" }, "default": [ "vk" ] }, "searchQueries": { "title": "Search queries", "type": "array", "description": "Use this when you want to discover VK communities by keyword. Enter one phrase per line, for example 'gaming' or 'маркетинг'. Defaults to an empty list; with vkAccessToken the Actor uses VK groups.search, otherwise it tries public web search. Not a place for VK URLs; put known communities in targets.", "items": { "type": "string" }, "default": [] }, "maxGroups": { "title": "Max groups", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Use this to cap the total number of billable group records saved across targets and searches. Example: 50 returns at most 50 group rows. Defaults to 50 and is clamped to 1-1000 at runtime. Not a page count; each saved VK group is one billable event.", "default": 50 }, "maxGroupsPerSearch": { "title": "Max groups per search", "minimum": 1, "maximum": 250, "type": "integer", "description": "Use this to limit how many communities each keyword can add before the Actor moves to the next search query. Example: 25 keeps broad terms from consuming the whole run. Defaults to 25 and is clamped to maxGroups and 250. Not used for direct targets.", "default": 25 }, "vkAccessToken": { "title": "VK access token", "type": "string", "description": "Use this when you have a VK API service or user access token and want structured API results, especially for keyword search. Paste only the token string, for example one generated from a VK app at dev.vk.com. Defaults to blank, which uses public tokenless browsing where possible. Not your VK password, login cookie, or private account session." }, "proxyCountry": { "title": "Proxy country", "enum": [ "RU", "BY", "KZ", "UA", "UZ", "DE", "US" ], "type": "string", "description": "Use this to choose the Residential proxy country used to reach VK. Example: 'RU' is recommended because VK often throttles datacenter and non-CIS routes. Defaults to RU. Not a content-language filter; it only controls network egress.", "default": "RU" }, "includeRawData": { "title": "Include raw VK data", "type": "boolean", "description": "Use this when you need the raw VK API group object for debugging or custom downstream parsing. Defaults to false for smaller, cleaner exports. Browser-route rows include only a small raw diagnostic object because VK HTML is too large for normal datasets. Not needed for spreadsheet exports or MCP clients.", "default": false }, "saveHtmlSnapshot": { "title": "Save HTML snapshot", "type": "boolean", "description": "Use this when troubleshooting VK public-page markup or a suspected selector drift. Example: true writes DEBUG_GROUP_DOM and DEBUG_GROUP_SEARCH records to the key-value store. Defaults to false for normal runs. Not needed when vkAccessToken is supplied and the API route succeeds.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Use this only when you need to override the default Apify Residential proxy. Example: keep the default Residential proxy unless you have a tested VK route. Defaults to Apify Residential in proxyCountry. Not required for normal runs; weak proxies can lower VK reliability.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } } ```