# Zillow Agent Scraper — Licenses, Contacts, Sales Stats (`sian.agency/zillow-agent-scraper`) Actor

Scrape Zillow agent profiles at scale — search by city or lookup by username, URL, or zuid. Returns verified contacts, license numbers + expiry, MLS IDs, service areas, sales stats, active for-sale + sold portfolios, and reviews. Built for brokerage recruiting, lead gen, and CRM enrichment.

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

## Pricing

from $19.00 / 1,000 extracted agents

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Zillow Agent Scraper — Licenses, Contacts, Sales Stats 🏠

[![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/SI%C3%81N-Smart%20Idealista%20Scraper-E60023)](https://apify.com/sian.agency/smart-idealista-scraper?fpr=sian) [![Bayut Property Scraper](https://img.shields.io/badge/SI%C3%81N-Bayut%20Property%20Scraper-93D500)](https://apify.com/sian.agency/bayut-property-scraper?fpr=sian) [![Redfin Property Scraper](https://img.shields.io/badge/SI%C3%81N-Redfin%20Property%20Scraper-A02021)](https://apify.com/sian.agency/redfin-property-scraper?fpr=sian)

#### 🎉 The only Zillow agent scraper that exposes license #, expiry, and MLS IDs — compliance-grade data at $25 per 1,000 agents on the Apify Standard plan.

##### Built for brokerage recruiters, lead-gen SaaS founders, and MLS/CRM data engineers — get the fields competitors strip out.

***

### 🔍 What is the Zillow Agent Scraper — and when should you use it?

The **Zillow Agent Scraper** turns a city name, a profile URL or a username into clean, structured agent rows you can filter, export and feed straight into a spreadsheet, CRM or AI agent. No Zillow account, no portal API key, no browser automation to maintain.

**Use it when you need:** agent names, brokerages, license numbers with state and expiry, MLS organisation UIDs and agent MLS IDs. It also returns service areas, phone and email, parsed sales stats, for-sale and for-rent portfolios, sold history, and client reviews.

**Use something else when:** you want the *properties* rather than the people behind them. [Zillow Property Scraper](https://apify.com/sian.agency/zillow-property-scraper?fpr=sian) covers listings. For markets where Realtor.com has the better agent roster, use [Realtor.com Agent Scraper](https://apify.com/sian.agency/realtor-agent-scraper?fpr=sian).

***

### 🤖 Use with AI agents

Already connected to the [Apify MCP server](https://mcp.apify.com)? Just ask for this Actor by name: sian.agency/zillow-agent-scraper

**Your agent can pay for its own runs.** This Actor is eligible for [agentic payments](https://docs.apify.com/platform/actors/publishing/monetize), so an agent can discover it, run it and settle the bill over [x402](https://www.x402.org/) (USDC on Base) or [Skyfire](https://www.skyfire.xyz/) — without an Apify account or API token of its own. Billing is the same either way: per agent successfully extracted, never for errors.

Otherwise copy this prompt into Claude, ChatGPT, Cursor or any MCP-enabled assistant:

```text
I want to build a list of real-estate agents in a market, with license and contact
details, using the Apify Actor `sian.agency/zillow-agent-scraper`.

Use it when I need: agent names, brokerages, license number + state + expiry,
MLS agent IDs, service areas, phone, email, sales stats, sold history, reviews.

Don't use it when: I want the listings themselves rather than the agents —
use `sian.agency/zillow-property-scraper` instead.

How to call it: two modes. "search" paginates the Zillow agent directory for one
city — pass `location` like "Austin, TX" and `maxAgentsPerQuery`. "lookup" fetches
specific agents — pass `lookupTargets` as profile URLs or usernames.

Start with this input:
{
  "searchMode": "search",
  "location": "Austin, TX",
  "maxAgentsPerQuery": 25,
  "fetchAgentDetails": true,
  "includeReviews": false
}

Ask me which city or which agents I want, then run the Actor and summarise the
results as a table sorted by sales in the last twelve months.
```

**Things you can ask your agent for:**

- *"Find every Zillow agent in Austin with a current Texas license and an email, then draft a recruiting message for the top ten by sales volume."*
- *"Pull the Compass and Keller Williams agents in Miami, compare their median 12-month sales, and tell me which brokerage is growing."*
- *"Look up these fifteen agent profile URLs, get their MLS agent IDs, and match them against my CRM export."*

Machine-readable API, MCP config and OpenAPI definition for this Actor are published at [apify.com/sian.agency/zillow-agent-scraper.md](https://apify.com/sian.agency/zillow-agent-scraper.md).

***

### 📋 Overview

**Pull thousands of Zillow real-estate agents at scale** — search by city, lookup by URL/username, get **license #, expiry date, MLS IDs, service areas, parsed sales stats, contacts, sold history, and reviews** in one clean structured dataset.

**Why brokerage recruiters and lead-gen teams choose us:**

- ✅ **Compliance-grade data**: license number, state, status, expiration date per agent — every other Zillow agent scraper strips this out
- 🆔 **MLS Organisation UID + Agent MLS ID**: direct internal-MLS matching, no fuzzy joins, no string fights
- 🗺 **Service-area mapping**: Zillow `regionId` + URL for every market the agent works — perfect territory targeting
- 📈 **Parsed numeric sales stats**: `totalSales`, `salesLastTwelveMonths`, `averagePrice`, `priceRange.min/max` — competitors return Zillow's raw `"$1.3M"` string
- 💎 **Optional deep-enrichment**: paginated for-sale, for-rent, full sold history (1,000+ rows per agent), and reviews — one toggle each
- ✨ **NEW**: HTML cohort report with top-brokerage breakdown, license-state coverage, median sales/agent, and Premier-Agent ratio

**Built by [SIÁN Agency](https://apify.com/sian.agency?fpr=sian)** — independent tool, not affiliated with Zillow Group, Inc.

***

### ✨ Features

- 🧭 **Two search modes**: city/state directory search **OR** direct lookup by profile URL/username/encodedZuid
- 📜 **License compliance fields** — number, state, status, license type, expiration date
- 🆔 **MLS identifiers** — `mls_ouid` + `mls_agent_id` arrays
- 🏠 **Business address + brokerage** — address1, city, state, postal code, brokerage name
- 📞 **Full contact** — cell, business, brokerage phones + email
- 📊 **Parsed sales stats** — totalSales, salesLastTwelveMonths, averagePrice (USD), priceRange
- 🗺 **Service areas** — regionIds + Zillow region URLs for every market covered
- 💰 **For-sale + for-rent portfolios** — paginated, with zpid, price, beds/baths, address, home type
- 📈 **Sold history** — past transactions with sold_date, price, represented side (buyer/seller/both)
- ⭐ **Reviews** — paginated client reviews with rating, comment, work description, agent rebuttal
- 📄 **HTML cohort report** — saved to key-value store with brokerage breakdown, state coverage, and sales KPIs

***

### 🎬 Quick Start

Run a search for Miami real-estate agents and get back full agent records with license, MLS, and contact data — in under a minute.

```bash
curl -X POST "https://api.apify.com/v2/acts/sian.agency~zillow-agent-scraper/runs?token=YOUR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"searchMode":"search","location":"Miami, FL","maxAgentsPerQuery":25,"fetchAgentDetails":true}'
```

***

### 🚀 Getting Started (3 Simple Steps)

#### Step 1: Pick your input mode

- **search**: enter a city + state like `"Miami, FL"` to paginate the agent directory
- **lookup**: paste profile URLs, usernames, or encodedZuids to fetch specific agents directly

#### Step 2: Toggle the enrichments you need

Set `includeForSale`, `includeForRent`, `includeSoldProperties`, `includeReviews` to `true` to paginate each agent's full portfolio. Skip them all to keep runs lean and cheap.

#### Step 3: Run the actor

Hit "Start" in the Apify Console, or POST to the API. Results stream to the dataset; the HTML cohort report lands in the key-value store as `report.html`.

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

- Clean structured agent records with compliance-grade fields
- An HTML market report ready to share with stakeholders
- A dataset exportable as JSON, CSV, or Excel directly from Apify

***

### 📥 Input Configuration

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `searchMode` | string | Yes | `search` or `lookup` |
| `location` | string | search mode | City + state, e.g. `"Miami, FL"` |
| `language` | string | No | Optional language filter, e.g. `"Spanish"` |
| `lookupTargets` | array | lookup mode | Profile URLs, usernames, or encodedZuids |
| `fetchAgentDetails` | boolean | No | Fetch full /agent/details per row (default true in search; always true in lookup) |
| `includeForSale` | boolean | No | Paginate active for-sale portfolio per agent |
| `includeForRent` | boolean | No | Paginate active rental portfolio per agent |
| `includeSoldProperties` | boolean | No | Paginate full sold history per agent |
| `includeReviews` | boolean | No | Paginate client reviews per agent |
| `maxAgentsPerQuery` | integer | No | Default 50, max 500 |
| `maxListingsPerAgent` | integer | No | Default 50, max 500 |
| `maxSoldPerAgent` | integer | No | Default 50, max 2,000 |
| `maxReviewsPerAgent` | integer | No | Default 25, max 500 |

**Example (search mode):**

```json
{
  "searchMode": "search",
  "location": "Austin, TX",
  "maxAgentsPerQuery": 100,
  "fetchAgentDetails": true,
  "includeSoldProperties": true,
  "maxSoldPerAgent": 100
}
```

**Example (lookup mode):**

```json
{
  "searchMode": "lookup",
  "lookupTargets": [
    "https://www.zillow.com/profile/RESalesForce",
    "ChrisLollipop"
  ],
  "includeReviews": true,
  "includeForSale": true
}
```

***

### 📤 Output

Results are saved to the Apify dataset with **28 fields** per agent including:

| Field | Type | Description |
|-------|------|-------------|
| `encodedZuid` | string | Zillow's stable agent ID (e.g. `X1-ZUx6y02vup6io9_88dzc`) |
| `username` | string | Zillow profile slug |
| `profileUrl` | string | Full Zillow profile page URL |
| `agentName` | string | Display name (e.g. "Dinorah de Cardenas - RESF") |
| `businessName` | string | Brokerage / team name |
| `licenses` | array | License #, state, status, type, expiration date |
| `mlsIds` | array | `mls_ouid` + `mls_agent_id` per active MLS |
| `serviceAreas` | array | regionId + text + Zillow URL for each market covered |
| `contact` | object | phoneNumbers (cell/business/brokerage), primaryPhone, email |
| `businessAddress` | object | Brokerage address (address1, city, state, postalCode) |
| `salesStats` | object | `totalSales`, `salesLastTwelveMonths`, `averagePrice` (USD), `priceRange.min/max` |
| `ratings` | object | average (1-5), count |
| `isPremierAgent` | boolean | Paid Zillow tier flag |
| `isTopAgent` | boolean | Zillow Top Agent flag |
| `forSaleListings` | array | Active sale listings (when enriched) |
| `forRentListings` | array | Active rental listings (when enriched) |
| `pastSales` | array | Sold properties with sold_date + represented side |
| `reviews` | array | Client reviews with rating, comment, work description |
| `counts` | object | Counts + Zillow-reported totals for all bundles |

**Example record:**

```json
{
  "encodedZuid": "X1-ZUx6y02vup6io9_88dzc",
  "username": "RESalesForce",
  "agentName": "Dinorah de Cardenas - RESF",
  "businessName": "Real Estate Sales Force",
  "licenses": [
    {"text":"3160356","state":"FL","status":"active","license_type":"agent","expiration":"2027-09-30"}
  ],
  "mlsIds": [{"mls_ouid":"M00000151","mls_agent_id":"3160356"}],
  "salesStats": {
    "totalSales": 1253,
    "salesLastTwelveMonths": 23,
    "averagePrice": 1300000,
    "priceRange": {"min":144000,"max":19000000}
  },
  "contact": {
    "phoneNumbers":{"cell":"(305) 305-0300","business":"(305) 392-1497"},
    "primaryPhone":"(305) 305-0300",
    "email":"thedinorahgroup@gmail.com"
  },
  "ratings": {"average":5,"count":840},
  "counts": {"forSale":8,"forRent":0,"pastSales":10,"reviews":5,"pastSalesTotal":1253}
}
```

***

### 💼 Use Cases & Examples

#### 1. Brokerage Recruiting

**Recruiting teams at Compass, Keller Williams, and eXp Realty pulling top-producing agents in a target market.**

**Input:** `searchMode: "search"`, `location: "Austin, TX"`, `maxAgentsPerQuery: 200`
**Output:** 200 agents with license #, sales/year, average deal, brokerage, email, phone
**Use:** Filter by `salesLastTwelveMonths > 15`, then push to your CRM

#### 2. Lead-Gen SaaS

**B2B SaaS founders building real-estate agent contact-enrichment products.**

**Input:** Bulk `lookupTargets` array of usernames from your own pipeline
**Output:** Verified licenses, contact info, MLS IDs ready to ship as API responses to your customers
**Use:** Power your own product without maintaining Zillow scrapers or proxy fleets

#### 3. Real-Estate Analytics

**Analytics teams tracking agent productivity and top-producer concentration by region.**

**Input:** `searchMode: "search"`, run weekly across 20 metro areas
**Output:** Time-series of `salesLastTwelveMonths` per agent, with brokerage attribution
**Use:** Build market-share dashboards, top-100-agent leaderboards, brokerage productivity reports

#### 4. MLS / CRM Integration

**Data engineers matching Zillow agent profiles to internal MLS feeds.**

**Input:** `searchMode: "lookup"`, push every agent in your CRM as a lookupTarget
**Output:** `mlsIds[]` arrays for direct join keys, plus reviews and service areas
**Use:** Match your own agent records to Zillow profiles without name-based joins

#### 5. Compliance & Due-Diligence

**Compliance teams at ad networks, mortgage lenders, and relocation platforms vetting agents.**

**Input:** `lookupTargets`: individual agent URLs as deals come in
**Output:** Current license status + expiration date per agent
**Use:** Block partnerships where `licenses[0].status != "active"` or expiration is within 30 days

#### 6. Real-Estate Lead Generation

**Lead-gen agencies building "top agents in your city" pages for SEO.**

**Input:** `searchMode: "search"` per city, `includeReviews: true`
**Output:** Agent rankings by rating + sales volume, with embedded reviews for testimonials
**Use:** Programmatic SEO pages, agent directories, "find a top realtor" widgets

***

### 🔗 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/zillow-agent-scraper').call({
  searchMode: 'search',
  location: 'Miami, FL',
  maxAgentsPerQuery: 50,
  fetchAgentDetails: true,
  includeSoldProperties: true,
  maxSoldPerAgent: 100
});

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

#### Python

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

run = client.actor('sian.agency/zillow-agent-scraper').call(
    run_input={
        'searchMode': 'search',
        'location': 'Austin, TX',
        'maxAgentsPerQuery': 100,
        'fetchAgentDetails': True,
        'includeReviews': True
    }
)

for agent in client.dataset(run['defaultDatasetId']).iterate_items():
    print(agent['agentName'], agent.get('salesStats', {}).get('salesLastTwelveMonths'))
```

#### cURL

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

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

1. **Trigger**: Schedule weekly per target metro area, or webhook from your CRM when a new agent record needs enrichment
2. **HTTP Request**: Call the actor API with the search query or lookup targets
3. **Process**: Parse the JSON dataset; filter by license status, sales volume, or brokerage
4. **Action**: Push to HubSpot/Salesforce/Airtable, trigger outreach sequences, or write to your data warehouse

***

### 📊 Performance & Pricing

#### FREE Tier (Try It Now)

- **5 agents** per run — full feature access with license, MLS, contact data
- 1 query per run
- Enrichment toggles disabled (upgrade to unlock for-sale, for-rent, sold, reviews)
- No credit card required
- Perfect for evaluating data quality before bulk runs

#### PAID Tier (Production Ready)

- **Unlimited** agents per run
- Unlimited queries per run
- All enrichment toggles available (for-sale, for-rent, sold, reviews)
- Pay-per-event: only charged for agents successfully extracted + enriched

#### Live Pricing (per-event)

| Tier | Actor Start | Agent Extracted | Agent Enriched |
|---|---|---|---|
| FREE | $0.050 | $0.075 | $0.240 |
| BRONZE | $0.005 | **$0.025** | $0.080 |
| SILVER | $0.005 | $0.022 | $0.070 |
| GOLD | $0.005 | $0.019 | $0.060 |
| PLATINUM | $0.005 | $0.013 | $0.040 |
| DIAMOND | $0.005 | $0.008 | $0.024 |

**Agent Extracted** fires once per agent record returned (includes license, MLS, contact, sales stats, reviews summary).
**Agent Enriched** fires once per agent when at least one enrichment endpoint (for-sale, for-rent, sold history, reviews) successfully paginated.

💰 **Mid-premium positioning** — significantly cheaper than premium lead-enrichment competitors ($0.05-$0.08 per agent), and the only scraper at any price point that exposes license #, expiry, and MLS IDs.

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

***

### ❓ Frequently Asked Questions

**Q: How many agents can I pull per run?**
A: FREE tier: 5 agents, 1 query, no enrichment. PAID tier: unlimited agents, unlimited queries, all enrichment toggles available.

**Q: What's the difference between `search` and `lookup` mode?**
A: `search` paginates Zillow's agent directory by city/state (e.g. all agents in Miami, FL). `lookup` fetches specific agents by profile URL, username, or encodedZuid — useful for enriching agents you already have.

**Q: Why does the search mode return ~15 agents per page?**
A: Zillow's `/agent/search` endpoint paginates at 15 agents per page. The actor handles pagination automatically up to `maxAgentsPerQuery`.

**Q: Why are some agents missing license data?**
A: Team profiles (e.g. "ONEPATH Team") often have no individual license registered on Zillow. Individual agent profiles consistently return license #, state, status, and expiration date.

**Q: Can I bypass Zillow's 500-result limit?**
A: The agent directory typically caps at ~500 results per query. Use multiple city searches (e.g. by neighbourhood: `"Brickell, Miami, FL"`, `"Coral Gables, FL"`) to enumerate beyond that cap.

**Q: What output formats are available?**
A: JSON, CSV, Excel, RSS, HTML, XML — export directly from the Apify dataset UI or via the API.

**Q: How accurate is the data?**
A: Data comes from public Zillow agent profiles. Licenses + MLS IDs are sourced directly from Zillow's API and reflect Zillow's current snapshot. Sales stats are parsed from Zillow's formatted strings (e.g. `"$1.3M"` → `1300000` USD).

**Q: How long does processing take?**
A: ~1 second per agent in search mode without enrichment. With full enrichment (for-sale + for-rent + sold + reviews), expect ~5-15 seconds per agent depending on portfolio size.

***

### 🐞 Troubleshooting

**"Zillow returned an empty profile for \[URL]"**

- Verify the username or URL is correct — paste the URL from the address bar of the agent's Zillow profile page
- Zillow sometimes returns a blank profile for a handle that is perfectly valid, at roughly one request in five. The actor already retries three times, so re-running the same input usually clears it
- Some profile slugs require the exact case used by Zillow

**"Missing ZILLOW_API_KEY environment variable"**

- This shouldn't happen on the Apify platform — secrets are pre-configured
- For local development, export `ZILLOW_API_KEY` before running

**Empty `licenses[]` for some agents**

- Team profiles typically don't carry an individual license — Zillow only displays licenses tied to the named individual
- Switch to individual agent lookups for compliance use cases

**Enrichment endpoints return fewer rows than `counts.*Total`**

- Zillow limits `/agent/for_sale`, `/agent/for_rent`, etc. to 4-5 rows per page; raise `maxListingsPerAgent` / `maxSoldPerAgent` and the actor will paginate further
- For agents with 1,000+ sold properties, set `maxSoldPerAgent: 1000` (default is 50)

***

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

Our actors are ethical and do not extract any private user data, such as personal email addresses of consumers, gender, or location. They only extract what the agent has chosen to share publicly on their Zillow profile page (the same fields any visitor can see). 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/).

***

### ⚠️ Trademark Disclaimer

This is an independent tool — **not affiliated with, endorsed by, sponsored by, or in any way officially connected with Zillow Group, Inc.** or any of its subsidiaries or affiliates. "Zillow" is a registered trademark of Zillow, Inc. All product names, logos, and brands are property of their respective owners. Data is sourced from publicly available agent profile pages.

***

### 🤝 Support

**Join our active support community**

- Report issues or request features via the Apify Console Issues tab
- Check the [SIÁN Agency Store](https://apify.com/sian.agency?fpr=sian) for more real-estate and lead-gen 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)**

# Changelog

This Actor's version history is a separate document: https://apify.com/sian.agency/zillow-agent-scraper/changelog.md

# Actor input Schema

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

How to find agents. **search** — paginate Zillow's agent directory by city/state. **lookup** — directly fetch one or more agents by username, profile URL, or encodedZuid.

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

City + state for the agent search, e.g. "Miami, FL" or "Austin, TX". Required when searchMode = search.

## `language` (type: `string`):

Optional agent language filter, e.g. "Spanish", "Portuguese", "Mandarin". Best-effort — Zillow returns the most relevant agents and language is a soft signal.

## `maxAgentsPerQuery` (type: `integer`):

Cap on how many agent records to return per search query. Default 50 (~3-4 pages). FREE tier hard-capped at 5.

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

List of Zillow agent profile URLs (https://www.zillow.com/profile/USERNAME), usernames (e.g. RESalesForce), or encodedZuids. Required when searchMode = lookup. Paste the URL exactly as it appears in your browser — a name with a space works either way (Christy%20Stuart or Christy Stuart), and a trailing slash or tracking query string is fine.

## `fetchAgentDetails` (type: `boolean`):

When in search mode, after each agent row from the directory, call /agent/details to retrieve license numbers, MLS IDs, full contact info, service areas, parsed sales stats, and embedded listing samples. Adds 1 upstream call per agent. Always on in lookup mode.

## `includeForSale` (type: `boolean`):

Per agent, paginate /agent/for_sale and attach the full active sale-listing portfolio (zpid, price, address, beds/baths). FREE tier: disabled.

## `includeForRent` (type: `boolean`):

Per agent, paginate /agent/for_rent and attach the full active rental portfolio. FREE tier: disabled.

## `includeSoldProperties` (type: `boolean`):

Per agent, paginate /agent/sold_properties and attach past transactions (price, sold_date, represented side). Can be 1000+ rows per agent — cap below. FREE tier: disabled.

## `includeReviews` (type: `boolean`):

Per agent, paginate /agent/reviews and attach client reviews (rating, comment, work description, agent rebuttal). FREE tier: disabled.

## `maxListingsPerAgent` (type: `integer`):

Hard cap on for-sale + for-rent rows per agent. Default 50.

## `maxSoldPerAgent` (type: `integer`):

Hard cap on sold-history rows per agent. Default 50. Some agents have 1000+ sold; raise this for full history.

## `maxReviewsPerAgent` (type: `integer`):

Hard cap on reviews rows per agent. Default 25.

## Actor input object example

```json
{
  "searchMode": "search",
  "location": "Miami, FL",
  "language": "Spanish",
  "maxAgentsPerQuery": 10,
  "lookupTargets": [
    "https://www.zillow.com/profile/RESalesForce",
    "ChrisLollipop"
  ],
  "fetchAgentDetails": true,
  "includeForSale": false,
  "includeForRent": false,
  "includeSoldProperties": false,
  "includeReviews": false,
  "maxListingsPerAgent": 50,
  "maxSoldPerAgent": 50,
  "maxReviewsPerAgent": 25
}
```

# Actor output Schema

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

Structured Zillow agent profiles with parsed sales stats, license numbers + expiry, MLS IDs, service areas, contacts, and optional listing/sold/review enrichment.

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

HTML summary with run stats, agent counts, license-state coverage, top-brokerage distribution, 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 = {
    "location": "Austin, TX",
    "maxAgentsPerQuery": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("sian.agency/zillow-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 = {
    "location": "Austin, TX",
    "maxAgentsPerQuery": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("sian.agency/zillow-agent-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 '{
  "location": "Austin, TX",
  "maxAgentsPerQuery": 10
}' |
apify call sian.agency/zillow-agent-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,sian.agency/zillow-agent-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/kvVqzg0SpvfGxxocK/builds/mRnBa5LzYMmNOf8Lm/openapi.json