# 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:** 31 total users, 18 monthly users, 42.5% 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/actors/running/actors-in-store.md#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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 for Public Communities

VK Groups Scraper is an Apify Actor for public VK (VKontakte) communities. Give it known group URLs, handles, numeric group IDs, or keyword queries, and it returns one normalized record per public group with fields such as group URL, name, members count, activity, type, verification and access status, avatar, website, city, country, links, contacts, source, and scrape timestamp. It is an Apify Actor usable through Apify MCP, so the same dataset can support human review, automation, and agent workflows.

### Best fit and connected workflows

This Actor fits workflows that begin with a public VK community identifier or a topic for discovery.

Use it for:

- CIS social research based on public VK communities
- community lead mapping from public group metadata
- topic-based community discovery
- public profile enrichment for downstream analysis
- routing from community discovery into content collection

A natural next step after community discovery is [VK Posts Scraper](https://apify.com/khadinakbar/vk-posts-scraper), which connects when your workflow moves from group identification to post-level collection for a known VK community.

### Practical scenario

A researcher starts with the topic `gaming` and a short list of known communities such as `vkvideo` and `club1`. The Actor returns rows with `name`, `groupUrl`, `membersCount`, `activity`, `website`, `city`, `country`, `sourceInput`, and `sourceRoute`.

The researcher can sort the results by members count, review the activity label, and decide which communities belong in a lead list or which ones should move into a content review workflow next.

### Input

| Field | Type | Purpose |
|---|---|---|
| `targets` | array of strings | Known VK community URLs, handles, or numeric IDs such as `vk`, `https://vk.com/vkvideo`, `club1`, `public1`, or `-1` |
| `searchQueries` | array of strings | Keyword discovery terms such as `gaming` or `маркетинг` |
| `maxGroups` | integer | Caps the total number of billable group records saved across the run |
| `maxGroupsPerSearch` | integer | Caps how many communities each keyword can add before the next query is processed |
| `vkAccessToken` | string | Optional VK API service or user access token for structured API results, especially for search |
| `proxyCountry` | string | Residential proxy country used to reach VK |
| `includeRawData` | boolean | Includes the raw VK API group object or compact browser diagnostic data |
| `saveHtmlSnapshot` | boolean | Stores HTML snapshots for markup troubleshooting |
| `proxyConfiguration` | object | Optional override for the default Apify Residential proxy setup |

Focused input example:

```json
{
  "targets": ["vk", "https://vk.com/vkvideo", "club1"],
  "searchQueries": ["gaming"],
  "maxGroups": 10,
  "vkAccessToken": "YOUR_VK_TOKEN",
  "proxyCountry": "RU",
  "includeRawData": false,
  "saveHtmlSnapshot": false
}
```

### Output

One record represents one public VK group or community.

| Field | Type | Meaning |
|---|---|---|
| `groupId` | integer or null | Numeric VK community ID when VK exposes it |
| `screenName` | string or null | VK community handle when available |
| `groupUrl` | string | Canonical VK community URL |
| `name` | string | Public display name |
| `description` | string or null | Public description or meta description when exposed |
| `status` | string or null | Short public status or profile text |
| `activity` | string or null | VK activity or category label |
| `type` | string or null | Community type such as group, page, or event |
| `isClosed` | boolean or null | Public closed/private signal when exposed |
| `accessStatus` | string or null | Normalized public access status |
| `isVerified` | boolean or null | VK verification state when exposed |
| `membersCount` | integer or null | Public member, follower, or subscriber count |
| `photoUrl` | string or null | Public avatar or Open Graph image URL |
| `coverUrl` | string or null | Public cover image URL |
| `website` | string or null | Public website link |
| `city` | string or null | Public city label |
| `country` | string or null | Public country label |
| `contacts` | array | Public contact objects exposed by the API |
| `links` | array | Public external or community links exposed by the API |
| `sourceInput` | string | Original target or search query that produced the record |
| `sourceType` | string | `target` or `search` |
| `sourceRoute` | string | `vk-api`, `browser-profile`, or `browser-search` |
| `searchQuery` | string or null | Keyword that produced the record |
| `scrapedAt` | string | ISO timestamp of normalization |
| `rawGroup` | object or null | Raw VK API group object or compact browser diagnostic data |

Illustrative output record:

```json
{
  "groupUrl": "https://vk.com/vk",
  "name": "VK",
  "membersCount": 12500000,
  "activity": "Internet media",
  "type": "page",
  "isVerified": true,
  "accessStatus": "public",
  "photoUrl": "https://sun9-1.userapi.com/example.jpg",
  "website": "https://vk.com/",
  "sourceInput": "vk",
  "sourceType": "target",
  "sourceRoute": "vk-api",
  "searchQuery": null,
  "scrapedAt": "2026-07-15T12:00:00.000Z"
}
```

### How it works

This Actor supports two public VK collection routes:

1. Direct targets use a tokenless browser route by default and can also use VK API data when a VK access token is provided.
2. Keyword search fits the workflow with `vkAccessToken`, where the Actor uses `groups.search`. When no token is supplied, it can fall back to public web search where possible.

Both routes normalize records into the same dataset schema, so you can move between direct lookup and discovery without changing downstream code. The Actor also writes terminal run details to `OUTPUT` and `RUN_SUMMARY` in the key-value store.

### Evergreen pricing

This Actor uses Pay per event pricing plus Apify platform usage.

- Actor start event: charged once when the Actor starts
- VK group scraped event: charged for each validated public VK group record saved to the default dataset

Open the live Pricing tab on Apify for the current pricing view. As an example, a run that saves fifty groups produces fifty group-scraped events plus one actor-start event. Apify platform usage is billed separately.

### Use with AI agents (MCP)

This Actor is available as an Apify Actor usable through Apify MCP. It is a structured tool for retrieving public VK community records from direct targets or search queries, with provenance fields that help agents interpret where each row came from.

**Exact Actor identity:** `khadinakbar/vk-groups-scraper`

Tool description: find public VK communities from known identifiers or keyword discovery, then return normalized rows with public metadata, provenance, and scrape timestamps.

> Find public VK communities for these topics and targets, then return one record per community with group URL, name, members count, activity, website, and source fields. Use the returned dataset rows as the source of truth for downstream selection.

Output interpretation for agents:

- `groupUrl` and `name` identify the community record
- `membersCount`, `activity`, `type`, and `isVerified` support grouping and ranking
- `sourceInput`, `sourceType`, `sourceRoute`, and `searchQuery` explain provenance
- `scrapedAt` shows when the record was normalized
- `rawGroup` can be useful when `includeRawData` is enabled

Scope and routing guidance:

- put known URLs, handles, and numeric IDs in `targets`
- put discovery terms in `searchQueries`
- use `vkAccessToken` for structured keyword discovery when available
- use `proxyCountry` to select the Residential egress region for VK access
- use `maxGroups` and `maxGroupsPerSearch` to shape record volume and billing counts
- the dataset is the primary machine-readable result; `RUN_SUMMARY` and `OUTPUT` add run-level context

### Apify API example

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({
  token: process.env.APIFY_TOKEN,
});

const input = {
  targets: ['vk', 'https://vk.com/vkvideo'],
  searchQueries: ['gaming'],
  maxGroups: 5,
  proxyCountry: 'RU',
};

const run = await client.actor('khadinakbar/vk-groups-scraper').call(input);

const datasetId = run.defaultDatasetId;
const { items } = await client.dataset(datasetId).listItems({ clean: true });

console.log('Dataset ID:', datasetId);
console.log('First records:', items);
```

### Best results and outcome guidance

Use `targets` when you already know the community. Use `searchQueries` when you want the Actor to discover public communities around a topic.

For structured discovery, add a VK access token. For debugging public-page markup, enable `saveHtmlSnapshot`. For downstream parsing, enable `includeRawData`.

The most useful lead-mapping fields are `name`, `groupUrl`, `membersCount`, `activity`, `website`, `city`, `country`, and `links`. The dataset overview view is tuned for those fields, and the lead list view highlights a shorter outreach-oriented subset.

### Design note

I found that the output contract always includes `groupUrl`, `name`, `sourceInput`, `sourceType`, `sourceRoute`, and `scrapedAt` as required fields, which makes every saved row traceable to its original input and route.

### FAQ

#### When should I use `targets` instead of `searchQueries`?

Use `targets` when you already know the VK community URL, handle, or numeric group ID. Use `searchQueries` when you want to discover public communities by topic.

#### Which workflow pairs naturally with this Actor after discovery?

If you want community content after you identify a group, pair this Actor with [VK Posts Scraper](https://apify.com/khadinakbar/vk-posts-scraper) to move from discovery into post-level collection.

#### What route is used for keyword discovery?

Keyword discovery uses `groups.search` when `vkAccessToken` is present, and it can fall back to public web search where possible.

#### What data fields are most useful for lead mapping?

`name`, `groupUrl`, `membersCount`, `activity`, `website`, `city`, `country`, and `links` are the strongest lead-list fields in the dataset view.

#### How does the Actor handle direct community targets?

Direct targets can be collected with the tokenless browser route, and they can also be resolved through VK API data when a token is supplied.

### Related Actors

- [VK Posts Scraper](https://apify.com/khadinakbar/vk-posts-scraper) - use after community discovery when the next step is post-level collection for a known VK group.

### Responsible use

Use this Actor for publicly accessible VK community data and in line with applicable laws, VK terms, and your own data-handling policies. It is designed for public groups and communities, and it returns structured public metadata for research, mapping, and downstream analysis.

# 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": 1,
  "maxGroupsPerSearch": 1,
  "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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "targets": [
        "vk"
    ],
    "searchQueries": [],
    "maxGroups": 1,
    "maxGroupsPerSearch": 1
};

// 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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "targets": ["vk"],
    "searchQueries": [],
    "maxGroups": 1,
    "maxGroupsPerSearch": 1,
}

# 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(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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"
  ],
  "searchQueries": [],
  "maxGroups": 1,
  "maxGroupsPerSearch": 1
}' |
apify call khadinakbar/vk-groups-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/vk-groups-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/bsb7W5iqYredTWToS/builds/ZHsu4G9ZJUaRMONnc/openapi.json