{
  "openapi": "3.0.1",
  "info": {
    "title": "Zillow Agents Finder & Reviews Scraper",
    "description": "Zillow Agents Finder & Reviews Scraper extracts Zillow agent profiles and reviews, including agent names, brokerages, ratings, review counts, customer feedback, phone numbers, service areas, and profile URLs. Ideal for lead generation, market research, and competitor analysis.",
    "version": "0.1",
    "x-build-id": "ni69v7qncSm1AaGMN"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/simpleapi~zillow-agents-finder/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-simpleapi-zillow-agents-finder",
        "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/simpleapi~zillow-agents-finder/runs": {
      "post": {
        "operationId": "runs-sync-simpleapi-zillow-agents-finder",
        "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/simpleapi~zillow-agents-finder/run-sync": {
      "post": {
        "operationId": "run-sync-simpleapi-zillow-agents-finder",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "targets": {
            "title": "🔗 Agent / Lender Profiles (URL, @screenName, or Name)",
            "uniqueItems": true,
            "type": "array",
            "description": "Bulk input — each item can be:\n• Full profile URL — `https://www.zillow.com/profile/REMAX EDGE`\n• Profile sub-tab URL — `https://www.zillow.com/profile/<name>/sales|rentals|sold|reviews`\n• Screen name with `@` prefix — `@REMAX EDGE`\n• Agent or lender name (free text) — runs a directory search\n\nLeave empty to run a pure location-based crawl. (Also accepts the base actor's `urls`/`query` keys.)",
            "items": {
              "type": "string"
            }
          },
          "searchMode": {
            "title": "📋 Search Mode",
            "enum": [
              "agents",
              "lenders"
            ],
            "type": "string",
            "description": "Which Zillow directory to target. (Also accepts the base actor's `operation` key.)"
          },
          "searchLocation": {
            "title": "📍 Location",
            "type": "string",
            "description": "City / state used as the geo seed for every directory search (e.g. `New York`, `Los Angeles, CA`). Required unless every entry in `targets` is a direct profile URL or `@screenName`. (Also accepts the base actor's `location` key.)"
          },
          "maxAgentProfiles": {
            "title": "🔢 Max Agent / Lender Profiles",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of agent/lender profiles returned across all queries. Set `0` for unlimited. (Also accepts the base actor's `limit` key.) Individual reviews are NOT capped by this — see 🔟 Max Reviews per Agent below."
          },
          "includeFullProfileDetail": {
            "title": "🧾 Full Agent Profile Detail",
            "type": "boolean",
            "description": "When ✅ — return the full agent profile (sales stats, licenses, service areas, address, phones, email, aboutMe bio, languages, specialties, …). When ❌ — return the compact card shape (id, name, screenName, url, avatar, business, location, phone, rating, reviews.count). (Also accepts the base actor's `agent_detail_info` key.) Leave unchecked/unset to inherit the base key's value."
          },
          "agentSpecialty": {
            "title": "🎯 Specialty Filter",
            "enum": [
              "",
              "first-time-home-buyers",
              "foreclosure",
              "investment-properties",
              "lot-or-land",
              "luxury-homes",
              "military-or-veterans",
              "new-construction",
              "property-management",
              "relocation",
              "rentals",
              "senior-communities",
              "vacation-short-term-rentals"
            ],
            "type": "string",
            "description": "Single specialty filter for the agents directory. Accepts a numeric code or a Zillow slug. (Also accepts the base actor's `specialty` key.)"
          },
          "agentLanguage": {
            "title": "🗣️ Language Filter",
            "enum": [
              "",
              "english",
              "arabic",
              "bengali",
              "cantonese",
              "farsi",
              "french",
              "german",
              "greek",
              "hebrew",
              "hindi",
              "hungarian",
              "italian",
              "japanese",
              "korean",
              "mandarin",
              "polish",
              "portuguese",
              "russian",
              "spanish",
              "filipino",
              "thai",
              "turkish",
              "vietnamese"
            ],
            "type": "string",
            "description": "Single language filter (display name). (Also accepts the base actor's `language` key.)"
          },
          "topAgentsOnly": {
            "title": "⭐ Top Agents only",
            "type": "boolean",
            "description": "Filter to Zillow-flagged top agents (agents only). (Also accepts the base actor's `is_top_agent` key.)"
          },
          "buyerFocusedAgents": {
            "title": "🛒 Specializes in buying",
            "type": "boolean",
            "description": "Filter to agents who focus on buyers (agents only). (Also accepts the base actor's `is_buying` key.)"
          },
          "sellerFocusedAgents": {
            "title": "💸 Specializes in selling",
            "type": "boolean",
            "description": "Filter to agents who focus on sellers (agents only). (Also accepts the base actor's `is_selling` key.)"
          },
          "fetchIndividualReviews": {
            "title": "📝 Fetch Individual Reviews",
            "type": "boolean",
            "description": "When ✅ — for every agent, additionally fetch the `/reviews` subtab and emit ONE row per real customer review (reviewerName, rating, reviewText, date, subRatings, agentResponse), linked back to the agent via `parentId`. Adds one extra request per agent. Default ON.",
            "default": true
          },
          "maxReviewsPerAgent": {
            "title": "🔟 Max Reviews per Agent",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "Cap on individual review rows collected per agent. Set `0` for unlimited (all reviews on the page). Default 10.",
            "default": 10
          },
          "includeDerivedMetrics": {
            "title": "📈 Rating Tier & Review Velocity",
            "type": "boolean",
            "description": "When ✅ — add two computed fields to each agent record: `ratingTier` (Elite 4.8+ / Strong 4.3-4.79 / Standard <4.3, null with 0 reviews) and `reviewVelocity` (reviews.count ÷ max(1, yearsOfExperience), null without a known years-of-experience). Zero extra requests. Default ON.",
            "default": true
          },
          "enableAiReviewTagging": {
            "title": "🤖 Enable AI Tagging",
            "type": "boolean",
            "description": "When ✅ — tags each review's `reviewText` and the agent's `aboutMe` bio with `aiSentiment` (positive/neutral/negative) and `aiThemes` (short keyword phrases). Requires 🔑 AI API Key below. When ❌ or no key — AI fields ship as `null`, all other data unaffected.",
            "default": false
          },
          "aiModel": {
            "title": "🤖 AI Model / Provider",
            "enum": [
              "claude-haiku-4-5",
              "claude-sonnet-5",
              "claude-opus-4-8",
              "claude-fable-5",
              "gpt-4o-mini",
              "gpt-4o",
              "gpt-4.1-mini",
              "gpt-4.1",
              "o3-mini",
              "o1",
              "gemini-2.0-flash-lite",
              "gemini-2.0-flash",
              "gemini-1.5-pro",
              "gemini-2.5-flash",
              "gemini-2.5-pro",
              "grok-2-latest",
              "grok-3-mini",
              "grok-3",
              "grok-beta",
              "deepseek-chat",
              "deepseek-reasoner",
              "sonar",
              "sonar-pro",
              "sonar-reasoning",
              "mistral-small-latest",
              "mistral-large-latest"
            ],
            "type": "string",
            "description": "Provider auto-detected from the name: claude-*=Anthropic, gpt-*/o1/o3=OpenAI, gemini-*=Google, grok-*=xAI, deepseek-*=DeepSeek, sonar*=Perplexity, mistral-*=Mistral. Cheaper mini/flash/haiku/lite models are recommended for this classification task.",
            "default": "claude-haiku-4-5"
          },
          "aiApiKey": {
            "title": "🔑 AI API Key",
            "type": "string",
            "description": "Your own API key for the selected provider (falls back to env vars ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / XAI_API_KEY / DEEPSEEK_API_KEY / PERPLEXITY_API_KEY / MISTRAL_API_KEY if left blank). Required only when AI Tagging is enabled."
          },
          "lenderSortBy": {
            "title": "📊 Lender Sort Order",
            "enum": [
              "relevance",
              "location",
              "rating"
            ],
            "type": "string",
            "description": "Sort order for the lender directory (lenders only). (Also accepts the base actor's `sort_lenders` key.)"
          },
          "lenderFieldSelection": {
            "title": "🧮 Lender Field Allowlist",
            "uniqueItems": true,
            "type": "array",
            "description": "Pick which fields to keep on each lender record. Leave empty to return every field. Values map to keys on Zillow's lender profile (`displayUser`) payload. (Also accepts the base actor's `lender_fields` key.)",
            "items": {
              "type": "string",
              "enum": [
                "aboutMe",
                "address",
                "cellPhone",
                "companyName",
                "confirmedReviews",
                "contactLenderFormDisclaimer",
                "employerMemberFDIC",
                "employerScreenName",
                "equalHousingLogo",
                "faxPhone",
                "hideCellPhone",
                "individualName",
                "languagesSpoken",
                "memberFDIC",
                "nmlsType",
                "officePhone",
                "rating",
                "recentReviews",
                "stateLicenses",
                "stateSponsorships",
                "title",
                "totalReviews"
              ]
            }
          },
          "proxyConfiguration": {
            "title": "Proxy settings",
            "type": "object",
            "description": "By default the actor sends requests **without a proxy**. If Zillow blocks the request, the actor automatically falls back to **Apify datacenter** → **Apify residential** (with 3 retries on residential). Override here to force a specific group.",
            "default": {
              "useApifyProxy": false
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}