# Immobiliare.it Agency Scraper — Contacts & Listings (`sian.agency/immobiliare-agent-scraper`) Actor

Scrape Immobiliare.it real estate agencies — search agenzie immobiliari by Italian comune, enrich by agency id or URL. Returns phone numbers, agency website, description, geo, portfolio and sold counts, plus full listing portfolios. For lead gen, CRM enrichment, and competitor intel.

- **URL**: https://apify.com/sian.agency/immobiliare-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 $2.00 / 1,000 listing extracteds

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

## Immobiliare.it Agency Scraper — Contacts, Portfolios & Leads 🚀

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

#### 🎉 The first agency-intelligence scraper for Italy — direct phone numbers, agency websites, portfolio + sold counts for every agenzia immobiliare
##### Built for proptech lead-gen teams, brokerage recruiters, and competitor analysts working the Italian market

---

### 📋 Overview

**Need every real estate agency in Milano, Roma, or any Italian comune — with someone to actually call?** This actor turns Immobiliare.it's agency directory into clean, structured lead rows: agency name, **direct phone numbers**, the agency's **own website**, full description, geo coordinates, and hard productivity signals (**active portfolio count + sold count**) — plus the complete listing portfolio of any agency on demand.

**Why data teams choose us:**
- ✅ **Contact-grade rows**: direct phone numbers and off-portal agency websites on every enriched profile — the two fields lead-gen actually needs
- ⚡ **Three modes in one actor**: comune search, direct agency lookup (id or URL), and full listing-portfolio walks
- 🎯 **Productivity signals**: active portfolio count + sold count per agency — rank top performers before you reach out
- 💰 **Pay per row, not per month**: no subscription — a 40-agency city scan costs well under a dollar
- 💎 **Full portfolio intel**: every listing with price, full street address, coordinates, zone, surface, rooms, photos, and contract type
- ✨ **NEW**: cohort KPIs in every run report — phone coverage, median portfolio size, top-comuni breakdown

---

### ✨ Features

- 🔍 **Comune search**: up to 40 agencies per Italian comune (name or comune id) — query multiple comuni for full-market coverage
- 📞 **Contact enrichment**: phone numbers, agency website, and description are fetched automatically for every discovered agency
- 🏢 **Direct lookup**: paste agency ids or `immobiliare.it/agenzie-immobiliari/...` profile URLs for instant enriched profiles
- 🏠 **Portfolio walks**: paginate an agency's entire listing inventory — 20 listings per page until done
- 📊 **Productivity stats**: `listingsCount` + `soldCount` on every enriched agency row
- 🗺 **Full geo**: province, comune (with canonical id), macrozone/microzone, street, and lat/lng on listings
- 🏗 **Constructor flag**: distinguish developers from classic agencies
- 🔁 **Automatic dedupe**: agency and listing rows are deduplicated by id within a run
- 📄 **HTML run report**: phone/website coverage, median portfolio + sold counts, price medians, top comuni

---

### 🎬 Quick Start

Pick a mode, provide a comune (or agency ids), and run — results land in a structured dataset within seconds.

```bash
curl -X POST https://api.apify.com/v2/acts/sian.agency~immobiliare-agent-scraper/runs?token=YOUR_TOKEN \
-d '{"searchMode": "search", "locations": ["Milano"]}'
````

***

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Choose a mode

`search` (agencies by comune) · `lookup` (agency profiles by id/URL) · `listings` (full portfolio per agency).

#### Step 2: Provide your targets

Comune names like `Milano`, `Roma`, `Torino` — or agency ids / profile URLs harvested from a previous search.

#### Step 3: Run and export

Click Start. Export the dataset as JSON, CSV, or Excel.

**That's it! In under a minute, you'll have:**

- Agency lead rows with phone numbers and websites
- Portfolio + sold counts for performance ranking
- Full listing inventories with prices and addresses

***

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| searchMode | string | No | `search` (default), `lookup`, or `listings` |
| locations | array | search mode | Italian comune names or ids, e.g. `["Milano", "Roma"]` |
| lookupTargets | array | lookup/listings modes | Agency ids (`"44166"`) or profile URLs |
| fetchAgencyDetails | boolean | No | Enrich search rows with phones/website/counts (default `true`) |
| maxAgenciesPerLocation | integer | No | Cap per comune, up to the directory's 40-agency maximum |
| maxListingsPerAgency | integer | No | Portfolio row cap per agency in listings mode (default 100) |

**Example — agencies in Milano:**

```json
{
  "searchMode": "search",
  "locations": ["Milano"]
}
```

**Example — full portfolio of one agency:**

```json
{
  "searchMode": "listings",
  "lookupTargets": ["44166"],
  "maxListingsPerAgency": 200
}
```

***

### 📤 Output

Results are saved to the Apify dataset with **40+ fields**. Agency rows (`rowType: "agency"`):

| Field | Type | Description |
|-------|------|-------------|
| agencyName | string | Agency display name |
| phones / primaryPhone | array / string | Direct phone numbers |
| agencyWebsite | string | The agency's own website (off-portal) |
| agencyDescription | string | Full marketing description |
| agencyLocation | object | Province, comune (+ id), street, lat/lng |
| listingsCount | integer | Active portfolio size |
| soldCount | integer | Sold properties count |
| isConstructor | boolean | Developer vs classic agency |
| profileUrl | string | Public agency profile page |

Listing rows (`rowType: "listing"`): `propertyTitle`, `contract` (Vendita/Affitto), `propertyType`, `price` + `priceFormatted`, `surface`, `rooms`, `bathrooms`, `floor`, `listingLocation` (full street address + coordinates + zone), `photos`, `agency`, `listedAt`, `lastModifiedAt`, `listingUrl`.

**Example agency row:**

```json
{
  "rowType": "agency",
  "agencyId": "44166",
  "agencyName": "Affiliato Primacasa - Fast House S.r.l.",
  "phones": ["+390281269737", "0254108008"],
  "primaryPhone": "+390281269737",
  "agencyWebsite": "https://www.primacasa.it/it/agenzia/279/milano/milano/fast-house-s-r-l.html",
  "agencyLocation": { "province": { "locationId": "MI", "name": "Milano" }, "municipality": { "locationId": 8042, "name": "Milano" }, "latitude": 45.4478, "longitude": 9.2089 },
  "listingsCount": 59,
  "soldCount": 6,
  "isConstructor": false,
  "profileUrl": "https://www.immobiliare.it/agenzie-immobiliari/44166/affiliato-primacasa-fast-house/"
}
```

***

### 💼 Use Cases & Examples

#### 1. Agency lead generation

**Proptech and service vendors building call lists for the Italian market.**

**Input:** `search` mode with target comuni
**Output:** Agency rows with phones, websites, and descriptions
**Use:** Feed your CRM with verified, phone-bearing agency leads city by city.

#### 2. Competitor benchmarking

**Agencies and franchises tracking rival portfolios.**

**Input:** `listings` mode with competitor agency ids
**Output:** Every active listing with price, address, surface, and contract
**Use:** Monitor pricing strategy, stock mix, and zone coverage of any competitor.

#### 3. Brokerage recruiting & partnerships

**Networks scouting high-performing independents.**

**Input:** `search` across a region's comuni
**Output:** Portfolio + sold counts per agency
**Use:** Rank agencies by productivity, then reach out via the phone numbers on the row.

#### 4. Proptech data products

**SaaS teams enriching Italian agency records.**

**Input:** `lookup` mode with agency ids or profile URLs
**Output:** Enriched profiles with geo, contacts, and counts
**Use:** Power agency-matching, valuation, or directory products without building scraping infra.

#### 5. Market coverage mapping

**Analysts mapping agency density and developer activity.**

**Input:** `search` across many comuni
**Output:** Geo-coded agency rows with constructor flags
**Use:** Heatmap which brands dominate each comune and macrozone.

***

### 🔗 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/immobiliare-agent-scraper').call({
  searchMode: 'search',
  locations: ['Milano']
});

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/immobiliare-agent-scraper').call(
    run_input={'searchMode': 'search', 'locations': ['Milano']}
)

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

#### cURL

```bash
curl -X POST 'https://api.apify.com/v2/acts/sian.agency~immobiliare-agent-scraper/runs?token=YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"searchMode": "listings", "lookupTargets": ["44166"]}'
```

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

1. **Trigger**: Schedule (e.g. weekly per comune)
2. **HTTP Request**: Call the actor API
3. **Process**: Handle the JSON rows
4. **Action**: Push to CRM, sheet, or Slack

***

### 📊 Performance & Pricing

#### FREE Tier (Try It Now)

- **1 query, 5 agencies or 25 listing rows** per run — full field access, same data quality
- No credit card required
- Perfect for testing a comune before scaling

#### PAID Tier (Production Ready)

- **Unlimited** comuni, agencies, and portfolio rows per run
- Pay-per-result: agency profile rows and listing rows are charged only on success

💰 **No subscription** — unlike flat monthly agency-data tools, you pay only for the rows you pull.

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

***

### ❓ Frequently Asked Questions

**Q: How many agencies can I get per comune?**
A: The public directory returns up to 40 agencies per comune. For full-market coverage, run multiple comuni (e.g. all comuni of a province) — rows are deduplicated by agency id automatically.

**Q: Where do the phone numbers come from?**
A: From each agency's public profile page. Enrichment is on by default (`fetchAgencyDetails`); directory rows alone don't carry contacts.

**Q: Can I scrape one specific agency?**
A: Yes — use `lookup` mode with the agency id or its profile URL (`https://www.immobiliare.it/agenzie-immobiliari/<id>/`).

**Q: How do I get an agency's full inventory?**
A: `listings` mode walks the portfolio 20 listings per page until your cap or the end — each row includes price, address, coordinates, and photos.

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

**Q: Is this legal?**
A: We only extract publicly available business data. See the [legal section](#%EF%B8%8F-is-it-legal-to-scrape-data) below.

***

### 🐛 Troubleshooting

**A comune search returns 0 agencies**

- Check the spelling of the comune name (Italian spelling, e.g. "Torino" not "Turin")
- Try the numeric comune id instead (returned in `agencyLocation.municipality.locationId`)

**A lookup target fails validation**

- Targets must be numeric agency ids or full profile URLs like `https://www.immobiliare.it/agenzie-immobiliari/44166/`
- Harvest ids by running a `search` on the agency's comune first

**Fewer rows than expected in search mode**

- The directory caps at 40 agencies per comune and the FREE tier caps at 5 agencies per run
- Duplicate agencies across comuni are pushed only once per run

**Listings mode returns 0 rows for an agency**

- The agency may have an empty active portfolio — check `listingsCount` via `lookup` mode first

***

### ⚠️ Trademark Disclaimer

This actor is an independent tool and is **not affiliated with, endorsed by, or sponsored by Immobiliare.it S.p.A.** "Immobiliare.it" is a trademark of its respective owner and is used here only to identify the public website the data originates from. All data collected is publicly available business information.

***

### ⚖️ 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 repository
- 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

## `searchMode` (type: `string`):

How to collect data. **search** — find agencies by Italian comune (up to 40 per comune, enriched with phones + website by default). **lookup** — fetch enriched agency profiles directly by agency id or profile URL. **listings** — walk an agency's full listing portfolio (price, address, geo, photos), paginated.

## `locations` (type: `array`):

🔍 **AGENCY DISCOVERY:** One or more Italian comune names (e.g. "Milano", "Roma", "Torino") or numeric comune ids (Milano = 8042). Each comune returns up to 40 agencies — query multiple comuni for wider coverage.

💡 **TIP:** Click "Bulk edit" to paste one comune per line.

⚠️ **FREE tier:** 1 location per run.

## `lookupTargets` (type: `array`):

🏢 **DIRECT TARGETS:** Numeric agency ids (e.g. "44166", as returned by search mode) or agency profile URLs like `https://www.immobiliare.it/agenzie-immobiliari/44166/`.

💡 **TIP:** Run a comune search first to harvest agency ids, then feed them here for portfolio walks.

⚠️ **FREE tier:** 1 target per run.

## `fetchAgencyDetails` (type: `boolean`):

In search mode, enrich each directory row with the full agency profile — **phone numbers, agency website, description, geo location, portfolio + sold counts**. Directory rows alone carry none of these. Adds 1 call per agency. Always on in lookup mode.

## `maxAgenciesPerLocation` (type: `integer`):

Cap on agency records per comune search. The directory returns at most 40 agencies per comune (upstream cap). FREE tier hard-capped at 5 agencies per run.

## `maxListingsPerAgency` (type: `integer`):

Cap on portfolio rows per agency in listings mode (20 listings per page are fetched until this cap or the end of the portfolio). FREE tier hard-capped at 25 listing rows per run.

## Actor input object example

```json
{
  "searchMode": "search",
  "locations": [
    "Milano",
    "Roma"
  ],
  "lookupTargets": [
    "44166",
    "https://www.immobiliare.it/agenzie-immobiliari/44166/"
  ],
  "fetchAgencyDetails": true,
  "maxAgenciesPerLocation": 40,
  "maxListingsPerAgency": 100
}
```

# Actor output Schema

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

Structured agency profiles (phones, website, description, geo, portfolio + sold counts) and portfolio listing rows (price, address, surface, photos, contract).

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

HTML summary with run stats, phone/website coverage, portfolio and sold medians, top-comune breakdown, 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 = {
    "locations": [
        "Milano"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/immobiliare-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 = { "locations": ["Milano"] }

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/immobiliare-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 '{
  "locations": [
    "Milano"
  ]
}' |
apify call sian.agency/immobiliare-agent-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Immobiliare.it Agency Scraper — Contacts & Listings",
        "description": "Scrape Immobiliare.it real estate agencies — search agenzie immobiliari by Italian comune, enrich by agency id or URL. Returns phone numbers, agency website, description, geo, portfolio and sold counts, plus full listing portfolios. For lead gen, CRM enrichment, and competitor intel.",
        "version": "1.0",
        "x-build-id": "lkVl8LybeYobwcn4W"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/sian.agency~immobiliare-agent-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-sian.agency-immobiliare-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~immobiliare-agent-scraper/runs": {
            "post": {
                "operationId": "runs-sync-sian.agency-immobiliare-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~immobiliare-agent-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-sian.agency-immobiliare-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",
                "properties": {
                    "searchMode": {
                        "title": "🧭 Search Mode",
                        "enum": [
                            "search",
                            "lookup",
                            "listings"
                        ],
                        "type": "string",
                        "description": "How to collect data. **search** — find agencies by Italian comune (up to 40 per comune, enriched with phones + website by default). **lookup** — fetch enriched agency profiles directly by agency id or profile URL. **listings** — walk an agency's full listing portfolio (price, address, geo, photos), paginated.",
                        "default": "search"
                    },
                    "locations": {
                        "title": "📍 Locations (search mode)",
                        "type": "array",
                        "description": "🔍 **AGENCY DISCOVERY:** One or more Italian comune names (e.g. \"Milano\", \"Roma\", \"Torino\") or numeric comune ids (Milano = 8042). Each comune returns up to 40 agencies — query multiple comuni for wider coverage.\n\n💡 **TIP:** Click \"Bulk edit\" to paste one comune per line.\n\n⚠️ **FREE tier:** 1 location per run.",
                        "items": {
                            "type": "string"
                        },
                        "default": [
                            "Milano"
                        ]
                    },
                    "lookupTargets": {
                        "title": "🔎 Agency ids or URLs (lookup + listings modes)",
                        "type": "array",
                        "description": "🏢 **DIRECT TARGETS:** Numeric agency ids (e.g. \"44166\", as returned by search mode) or agency profile URLs like `https://www.immobiliare.it/agenzie-immobiliari/44166/`.\n\n💡 **TIP:** Run a comune search first to harvest agency ids, then feed them here for portfolio walks.\n\n⚠️ **FREE tier:** 1 target per run.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "fetchAgencyDetails": {
                        "title": "🏢 Fetch full agency details",
                        "type": "boolean",
                        "description": "In search mode, enrich each directory row with the full agency profile — **phone numbers, agency website, description, geo location, portfolio + sold counts**. Directory rows alone carry none of these. Adds 1 call per agency. Always on in lookup mode.",
                        "default": true
                    },
                    "maxAgenciesPerLocation": {
                        "title": "📊 Max agencies per location",
                        "minimum": 1,
                        "maximum": 40,
                        "type": "integer",
                        "description": "Cap on agency records per comune search. The directory returns at most 40 agencies per comune (upstream cap). FREE tier hard-capped at 5 agencies per run.",
                        "default": 40
                    },
                    "maxListingsPerAgency": {
                        "title": "🏠 Max listings per agency (listings mode)",
                        "minimum": 1,
                        "maximum": 2000,
                        "type": "integer",
                        "description": "Cap on portfolio rows per agency in listings mode (20 listings per page are fetched until this cap or the end of the portfolio). FREE tier hard-capped at 25 listing rows per run.",
                        "default": 100
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
