# Cian Agent Scraper — Russia Real Estate Agent Leads & Offers (`sian.agency/cian-agent-scraper`) Actor

Scrape Cian.ru real estate agents and developers at scale — agent profiles with email and verification level, full paginated offer portfolios with phone numbers, location-based agent discovery, and new-building (ЖК) complex details. Built for lead generation, recruiting, and Russia proptech.

- **URL**: https://apify.com/sian.agency/cian-agent-scraper.md
- **Developed by:** [SIÁN OÜ](https://apify.com/sian.agency) (community)
- **Categories:** Automation, Lead generation, Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 offer rows

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

## Cian Agent Scraper — Russia Real Estate Agent Leads & Offers 🏢

[![SIÁN Agency Store](https://img.shields.io/badge/Store-SI%C3%81N%20Agency-1AE392)](https://apify.com/sian.agency?fpr=sian) [![Store-Cian Property Scraper](https://img.shields.io/badge/Store-Cian%20Property%20Scraper-1AE392)](https://apify.com/sian.agency/cian-property-scraper?fpr=sian) [![Store-Zillow Agent Scraper](https://img.shields.io/badge/Store-Zillow%20Agent%20Scraper-1F4E79)](https://apify.com/sian.agency/zillow-agent-scraper?fpr=sian) [![Store-Idealista Scraper](https://img.shields.io/badge/Store-Idealista%20Scraper-E60023)](https://apify.com/sian.agency/smart-idealista-scraper?fpr=sian)

#### 🎉 The first agent & developer intelligence tool for Russia's biggest property portal — emails, verification levels, full offer portfolios with phone numbers, and new-building (ЖК) dossiers
##### Built for real-estate lead generation, brokerage recruiting, developer tracking, and Russia proptech datasets

---

### 📋 Overview

**Turn Russia's largest property marketplace into a structured agent & developer contact database** — discover agents by city, pull profiles complete with email and verification status, dump complete listing portfolios with phone numbers, and extract deep new-building (ЖК) dossiers.

**Why lead-gen and proptech teams choose us:**
- ✅ **Contact-grade agent data**: account email, account age, document-verification flag, and platform quality level per agent — fields no other tool on the market surfaces.
- ⚡ **Full offer portfolios with phones**: paginate an agent's or developer's entire inventory (hundreds of listings) with price, address, coordinates, metro access, and listed phone numbers.
- 🎯 **Location-based agent discovery**: no directory endpoint needed — feed a city and the actor deduplicates every active agent and developer from live listings.
- 💰 **Cheap per-row pricing**: offer rows from **$0.001**, enriched agent profiles priced for volume lead generation — pay only for what you extract.
- 💎 **New-building (ЖК) dossiers**: completion year, class, decoration, ceiling heights, delivery periods, and permit documents for any residential complex.
- ✨ **Stable numeric ids** for joining agents, offers, and complexes across runs.

### ✨ Features

- 🔍 **Find Agents by Location**: discover every active agent and developer in a city from live for-sale or for-rent listings.
- 👤 **Enriched Agent Profiles**: email, company, account age, verification flags, quality level, and offer count.
- 🏷 **Offer Portfolio Dump**: one clean row per listing — price, rooms, area, floor, address, coordinates, metro, building data, photos, and phones.
- 🏗 **New-Building (ЖК) Dossiers**: full residential-complex detail including class, decoration, ceiling heights, infrastructure, delivery periods, and documents.
- 🪪 **Verification Signals**: document-level identity checks and platform quality grading for recruiting-grade trust filtering.
- 🧭 **Bulk-friendly**: process many agent ids, profile URLs, or complex ids in one run.
- 📞 **Phone Numbers Included**: every offer row carries the listed contact phone.
- 📄 **HTML Run Report**: email/verification coverage, price and portfolio KPIs, per-query totals.

### 🎬 Quick Start

Pick a mode, give it a location or a list of ids, and run. Results land in a structured Apify dataset ready for CSV, Excel, or JSON export.

```bash
curl -X POST https://api.apify.com/v2/acts/sian.agency~cian-agent-scraper/runs?token=YOUR_TOKEN \
-H 'Content-Type: application/json' \
-d '{"mode": "findAgents", "location": "Москва", "maxAgents": 25}'
````

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Choose a mode

`findAgents` to discover agents in a city, `agentDetails` for known ids/URLs, `agentOffers` for full portfolios, or `newbuildingDetails` for complex dossiers.

#### Step 2: Provide input

A city name (e.g. "Санкт-Петербург"), a list of agent ids/profile URLs, or a list of complex ids/URLs.

#### Step 3: Run and export

Start the actor and download the dataset as JSON, CSV, or Excel.

**That's it! In minutes, you'll have:**

- A deduplicated list of agents and developers with contact emails
- Full listing portfolios with prices, addresses, and phone numbers
- New-building dossiers ready for investment analysis

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| mode | string | Yes | `findAgents`, `agentDetails`, `agentOffers`, or `newbuildingDetails` |
| location | string | For findAgents | City/area to discover agents in (e.g. "Москва") |
| searchType | string | No | `For_Sale` or `For_Rent` listings for discovery |
| maxAgents | integer | No | Unique agents to discover and enrich (default 10) |
| agentIds | array | For agentDetails / agentOffers | Numeric agent ids or profile URLs |
| maxOffersPerAgent | integer | No | Cap on portfolio rows per agent (default 56) |
| newbuildingIds | array | For newbuildingDetails | Numeric complex ids or complex URLs |

**Discover agents in a city:**

```json
{ "mode": "findAgents", "location": "Москва", "searchType": "For_Sale", "maxAgents": 25 }
```

**Dump an agent's full portfolio:**

```json
{ "mode": "agentOffers", "agentIds": ["116011436"], "maxOffersPerAgent": 200 }
```

**Pull new-building dossiers:**

```json
{ "mode": "newbuildingDetails", "newbuildingIds": ["4652900", "4096080"] }
```

### 📤 Output

Results are saved to the Apify dataset. Row shape depends on mode (`rowType`: `agentProfile`, `offer`, or `newbuilding`). Key fields:

| Field | Type | Description |
|-------|------|-------------|
| agentId | string | Stable numeric agent/company id |
| agentName | string | Agent or company name |
| email | string | Account email (the lead-gen field) |
| isUserIdentifiedByDocuments | boolean | Document-level verification flag |
| qualityLevel | object | Platform quality grading |
| offersCount | integer | Active offers on the profile |
| offerId | string | Listing id |
| price | object | Value, currency, formatted string |
| address | string | Full listing address |
| phones | array | Contact phone numbers on the offer |
| complexName | string | Residential complex (ЖК) name |
| completionYear | integer | Complex completion year |
| buildingClass | string | эконом / комфорт / бизнес / премиум |

**Example (agent profile):**

```json
{
  "rowType": "agentProfile",
  "agentId": "47710548",
  "agentName": "Илья Филипонский",
  "email": "Filiponsky@yandex.ru",
  "isDeveloper": false,
  "accountAge": "6 лет 5 месяцев",
  "isUserIdentifiedByDocuments": true,
  "qualityLevel": { "levelName": "Средний уровень", "levelOrder": 2, "levelSystemName": "medium" },
  "offersCount": 1
}
```

**Example (offer):**

```json
{
  "rowType": "offer",
  "offerId": "330241637",
  "offerTitle": "Квартира с окном в гардеробной",
  "price": { "value": 120048280, "currency": "RUB", "formatted": "120 048 280 ₽" },
  "rooms": 4,
  "totalArea": 108.7,
  "address": "Москва, ЮАО, р-н Донской, Шифт ЖК, к4",
  "phones": ["+79230707507"],
  "newbuilding": { "newbuildingId": "4652900", "name": "SHIFT (ШИФТ)" }
}
```

### 💼 Use Cases & Examples

#### 1. Agent Lead Generation

**Lead-gen teams building Russian real-estate contact lists.**

**Input:** a city name, or a list of agent ids.
**Output:** agent rows with email, account age, verification flag, and quality level.
**Use:** load straight into a CRM for B2B outreach to agents and developers.

#### 2. Brokerage Recruiting

**Recruiters headhunting productive agents.**

**Input:** `findAgents` on a target market.
**Output:** every active agent ranked by portfolio size, verification status, and quality level.
**Use:** shortlist top producers and reach out with confidence.

#### 3. Developer Intelligence

**Analysts tracking property developers (застройщики).**

**Input:** developer ids + new-building ids from offer rows.
**Output:** developer portfolios plus full ЖК dossiers (completion year, class, permit documents).
**Use:** monitor pipeline, pricing, and delivery timelines across projects.

#### 4. Competitor Benchmarking

**Agencies mapping a rival's inventory.**

**Input:** a competitor's agent or company id.
**Output:** their complete offer portfolio with prices, addresses, and phones.
**Use:** benchmark pricing, coverage, and listing velocity.

#### 5. Russia Proptech Datasets

**Data teams building Moscow and regional market datasets.**

**Input:** discovery across multiple cities.
**Output:** structured agent + offer rows with stable ids for joins.
**Use:** power dashboards, models, and market reports.

### 🔗 Integration Examples

#### JavaScript/Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: 'YOUR_TOKEN' });

const run = await client.actor('sian.agency/cian-agent-scraper').call({
  mode: 'findAgents',
  location: 'Москва',
  maxAgents: 25
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient('YOUR_TOKEN')

run = client.actor('sian.agency/cian-agent-scraper').call(
    run_input={'mode': 'agentOffers', 'agentIds': ['116011436'], 'maxOffersPerAgent': 200}
)

for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item)
```

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~cian-agent-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"mode": "newbuildingDetails", "newbuildingIds": ["4652900"]}'
```

#### Automation Workflows (N8N / Zapier / Make)

1. **Trigger**: Schedule or webhook
2. **HTTP Request**: Call actor API
3. **Process**: Handle JSON results
4. **Action**: Save to CRM, notify, or transform

### 📊 Performance & Pricing

#### FREE Tier (Try It Now)

- Up to **5 agents / 5 targets** per run — full feature access, same data quality
- No credit card required
- Perfect for testing and small projects

#### PAID Tier (Production Ready)

- **Unlimited** agents, offers, and complexes per run
- Full portfolio pagination
- Pay-per-event: only charged for rows successfully extracted

💰 **Cheap per-row pricing** — offer rows from $0.001, enriched agent profiles priced for volume lead generation.

🔗 [View current pricing](https://apify.com/sian.agency/cian-agent-scraper?fpr=sian)

### ❓ Frequently Asked Questions

**Q: How many agents can I process?**
A: FREE tier: up to 5 per run. PAID tier: unlimited.

**Q: Is there an agent-search endpoint?**
A: The source has none — the actor discovers agents from live listings in `findAgents` mode, then enriches each profile. You can also pass ids/URLs directly.

**Q: Where do I get agent ids?**
A: `findAgents` returns them, and every offer row carries the agent id. You can also paste `…/agents/<id>/` or `…/company/<id>/` profile URLs.

**Q: Does it include phone numbers and emails?**
A: Offer rows include listed phone numbers; agent profiles include the account email when the profile exposes one.

**Q: What output formats are available?**
A: JSON, CSV, and Excel — export directly from the Apify dataset.

**Q: Is this legal?**
A: Yes — only publicly available listing and profile data is collected. See the legal section below.

### 🐛 Troubleshooting

**No agents discovered for a location**

- Use the Russian place name (e.g. "Москва", "Санкт-Петербург").
- Try a larger city; small towns have few listings to discover agents from.

**An agent id returns no profile**

- The account may be blocked or removed upstream — harvest fresh ids via `findAgents`.

**A profile URL isn't accepted**

- Only `…/agents/<id>/` and `…/company/<id>/` URLs carry the account id. Developer pages don't — use `findAgents` to get the numeric id.

**Fewer offers than expected**

- Raise `maxOffersPerAgent`; some accounts list hundreds and the default caps at 56.

### ⚠️ Trademark Disclaimer

This is an independent tool and is **not affiliated with, endorsed by, or sponsored by** Cian (Циан) or its operators. "Cian" and "Циан" are trademarks of their respective owners. This actor collects only publicly available listing and profile data and is intended for lawful use.

### ⚖️ Is it legal to scrape data?

Our actors are ethical and do not extract any private user data, such as email addresses, gender, or location. They only extract what the user has chosen to share publicly. We therefore believe that our actors, when used for ethical purposes by Apify users, are safe.

However, you should be aware that your results could contain personal data. Personal data is protected by the **GDPR** in the European Union and by other regulations around the world. You should not scrape personal data unless you have a legitimate reason to do so. If you're unsure whether your reason is legitimate, consult your lawyers.

You can also read Apify's blog post on the [legality of web scraping](https://blog.apify.com/is-web-scraping-legal/).

### 🤝 Support

[![Telegram Support](https://img.shields.io/badge/Telegram-Support%20Group-0088cc?logo=telegram)](https://t.me/+vyh1sRE08sAxMGRi)

**Join our active support community**

- For issues or questions, open an issue in the actor's Console Issues tab
- Check [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more automation tools
- 📧 <apify@sian-agency.online>

***

**Built by [SIÁN Agency](https://www.sian-agency.online)** | **[More Tools](https://apify.com/sian.agency?fpr=sian)**

# Actor input Schema

## `mode` (type: `string`):

**findAgents** — discover agents/developers in a location (listing search → dedupe → enriched profiles). **agentDetails** — fetch profiles for known agent ids/URLs. **agentOffers** — dump the full offer portfolio of each agent id/URL (one row per offer, phones included). **newbuildingDetails** — fetch new-building (ЖК) complex dossiers by id/URL.

## `location` (type: `string`):

City or area to discover agents in, e.g. "Москва", "Санкт-Петербург", "Казань". Free text — resolved by the source. Required when mode = findAgents.

## `searchType` (type: `string`):

Which listings to walk while discovering agents: for-sale or for-rent inventory.

## `maxAgents` (type: `integer`):

How many unique agent/developer profiles to discover and enrich. Default 10. FREE tier hard-capped at 5.

## `agentIds` (type: `array`):

Numeric Cian agent/company ids (e.g. "47710548") or profile URLs (…cian.ru/agents/47710548/ or …cian.ru/company/140116723/). Ids are returned by findAgents mode. Required for agentDetails and agentOffers.

## `maxOffersPerAgent` (type: `integer`):

Cap on portfolio rows per agent (28 offers per page upstream). Default 56 (~2 pages). Some developers list hundreds.

## `newbuildingIds` (type: `array`):

Numeric ЖК ids (e.g. "4652900") or complex URLs (…cian.ru/zhiloy-kompleks-shift-moskva-4652900/). Ids also appear on offer rows (newbuilding.id). Required for newbuildingDetails.

## Actor input object example

```json
{
  "mode": "findAgents",
  "location": "Санкт-Петербург",
  "searchType": "For_Sale",
  "maxAgents": 10,
  "agentIds": [
    "47710548",
    "https://www.cian.ru/company/140116723/"
  ],
  "maxOffersPerAgent": 56,
  "newbuildingIds": [
    "4652900"
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

Structured rows — agent profiles (email, verification, quality level), portfolio offers (price, address, metro, phones), and new-building dossiers (completion, class, documents).

## `htmlReport` (type: `string`):

HTML summary with run stats, email/verification coverage, portfolio and price KPIs, and per-query totals.

# 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 = {
    "mode": "findAgents",
    "location": "Москва",
    "maxAgents": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/cian-agent-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 = {
    "mode": "findAgents",
    "location": "Москва",
    "maxAgents": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/cian-agent-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 '{
  "mode": "findAgents",
  "location": "Москва",
  "maxAgents": 10
}' |
apify call sian.agency/cian-agent-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=sian.agency/cian-agent-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Cian Agent Scraper — Russia Real Estate Agent Leads & Offers",
        "description": "Scrape Cian.ru real estate agents and developers at scale — agent profiles with email and verification level, full paginated offer portfolios with phone numbers, location-based agent discovery, and new-building (ЖК) complex details. Built for lead generation, recruiting, and Russia proptech.",
        "version": "1.0",
        "x-build-id": "MZyABXMGQmBDLLJoh"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/sian.agency~cian-agent-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-sian.agency-cian-agent-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/sian.agency~cian-agent-scraper/runs": {
            "post": {
                "operationId": "runs-sync-sian.agency-cian-agent-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/sian.agency~cian-agent-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-sian.agency-cian-agent-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",
                "required": [
                    "mode"
                ],
                "properties": {
                    "mode": {
                        "title": "🧭 Mode",
                        "enum": [
                            "findAgents",
                            "agentDetails",
                            "agentOffers",
                            "newbuildingDetails"
                        ],
                        "type": "string",
                        "description": "**findAgents** — discover agents/developers in a location (listing search → dedupe → enriched profiles). **agentDetails** — fetch profiles for known agent ids/URLs. **agentOffers** — dump the full offer portfolio of each agent id/URL (one row per offer, phones included). **newbuildingDetails** — fetch new-building (ЖК) complex dossiers by id/URL.",
                        "default": "findAgents"
                    },
                    "location": {
                        "title": "📍 Location (findAgents mode)",
                        "type": "string",
                        "description": "City or area to discover agents in, e.g. \"Москва\", \"Санкт-Петербург\", \"Казань\". Free text — resolved by the source. Required when mode = findAgents.",
                        "default": "Москва"
                    },
                    "searchType": {
                        "title": "🏠 Listing type for discovery (findAgents mode)",
                        "enum": [
                            "For_Sale",
                            "For_Rent"
                        ],
                        "type": "string",
                        "description": "Which listings to walk while discovering agents: for-sale or for-rent inventory.",
                        "default": "For_Sale"
                    },
                    "maxAgents": {
                        "title": "👥 Max agents (findAgents mode)",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "How many unique agent/developer profiles to discover and enrich. Default 10. FREE tier hard-capped at 5.",
                        "default": 10
                    },
                    "agentIds": {
                        "title": "🆔 Agent ids or profile URLs (agentDetails + agentOffers modes)",
                        "type": "array",
                        "description": "Numeric Cian agent/company ids (e.g. \"47710548\") or profile URLs (…cian.ru/agents/47710548/ or …cian.ru/company/140116723/). Ids are returned by findAgents mode. Required for agentDetails and agentOffers.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxOffersPerAgent": {
                        "title": "🏷 Max offers per agent (agentOffers mode)",
                        "minimum": 1,
                        "maximum": 2000,
                        "type": "integer",
                        "description": "Cap on portfolio rows per agent (28 offers per page upstream). Default 56 (~2 pages). Some developers list hundreds.",
                        "default": 56
                    },
                    "newbuildingIds": {
                        "title": "🏗 New-building ids or URLs (newbuildingDetails mode)",
                        "type": "array",
                        "description": "Numeric ЖК ids (e.g. \"4652900\") or complex URLs (…cian.ru/zhiloy-kompleks-shift-moskva-4652900/). Ids also appear on offer rows (newbuilding.id). Required for newbuildingDetails.",
                        "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
                                    }
                                }
                            },
                            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```