{
  "openapi": "3.0.1",
  "info": {
    "title": "Homes.com Scraper: For Sale, Rent, Sold & Open Houses",
    "description": "Scrape US property records from Homes.com. Pick a city, state or ZIP and a channel (for sale, for rent, recently sold, open houses, foreclosures), or paste links. One flat row per property with price, beds, baths, size, address, geo, agent and brokerage.",
    "version": "1.0",
    "x-build-id": "aHPyixhgiGz3bhfBo"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/abotapi~homes-com-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-abotapi-homes-com-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/abotapi~homes-com-scraper/runs": {
      "post": {
        "operationId": "runs-sync-abotapi-homes-com-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/abotapi~homes-com-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-abotapi-homes-com-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": {
          "mode": {
            "title": "Mode",
            "enum": [
              "search",
              "url"
            ],
            "type": "string",
            "description": "search = pick a US location and a listing channel, and get every matching property. url = paste homes.com search or property links and get only those.",
            "default": "search"
          },
          "location": {
            "title": "Location",
            "type": "string",
            "description": "A US city and state ('Austin, TX'), or a 5-digit ZIP code ('78701'). Accepted in any casing and with or without the comma.",
            "default": "Austin, TX"
          },
          "zipCode": {
            "title": "ZIP code (optional)",
            "type": "string",
            "description": "Optional. Narrow the search to a single 5-digit US ZIP code inside the location above."
          },
          "minBedrooms": {
            "title": "Bedrooms",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Optional. homes.com exposes bedroom filtering as one fixed page per count, so only 1 to 5 can be requested and the value matches listings with exactly that bedroom count. Leave empty for no bedroom filter."
          },
          "maxPrice": {
            "title": "Maximum price (USD)",
            "minimum": 0,
            "type": "integer",
            "description": "Optional. homes.com only publishes fixed maximum-price pages: 800000, 900000, 1000000, 1500000 or 2000000. Any other value is rejected with a clear message rather than silently ignored. Leave empty for no price ceiling."
          },
          "sort": {
            "title": "Sort order",
            "enum": [
              "relevance",
              "newest"
            ],
            "type": "string",
            "description": "Result ordering. 'Newest' puts the most recently listed properties first, which is the useful setting when you cap the run with Max items.",
            "default": "relevance"
          },
          "urls": {
            "title": "Homes.com links",
            "uniqueItems": true,
            "type": "array",
            "description": "Only used when mode = url. A property link always reads its full property page, so it always bills the detail surcharge. A search link is walked like search mode.",
            "items": {
              "type": "string"
            }
          },
          "listingType": {
            "title": "Listing channel",
            "enum": [
              "for_sale",
              "houses_for_sale",
              "condos_for_sale",
              "townhouses_for_sale",
              "multi_family_for_sale",
              "land_for_sale",
              "for_rent",
              "houses_for_rent",
              "condos_for_rent",
              "townhouses_for_rent",
              "apartments_for_rent",
              "sold",
              "open_houses",
              "foreclosure"
            ],
            "type": "string",
            "description": "Which homes.com channel to read. 'Recently sold' returns closed sales with the sale date, days on market and price per square foot. 'Open houses' returns only listings with a scheduled open house.",
            "default": "for_sale"
          },
          "fetchDetails": {
            "title": "Fetch full property details",
            "type": "boolean",
            "description": "Reads each property page and adds the sections that do not exist on a result card: price and property history (with list-to-sale percentages and price per square foot), multi-year tax history with land and improvement assessments, grouped home details, HOA fees, parking, utilities, schools, highlights and the full listing description. Adds one page read per listing and bills a per-listing detail-enrichment surcharge only for listings actually returned.",
            "default": false
          },
          "maxItems": {
            "title": "Max items (per run, 0 = unlimited)",
            "minimum": 0,
            "type": "integer",
            "description": "The single cap on the run: stop after this many property rows across all searches and URLs. Defaults to 20 so a run stays small unless you raise it. 0 = unlimited, bounded only by the natural end of results (or Max pages, if set).",
            "default": 20
          },
          "maxPages": {
            "title": "Max pages per search (0 = unlimited)",
            "minimum": 0,
            "type": "integer",
            "description": "Optional hard cap on the number of result pages walked per search or pasted search link. Each page carries up to 40 listings. 0 (default) means no page limit: the walk stops naturally on a short page, an empty page, or a page that repeats listings already collected.",
            "default": 0
          },
          "resumeFromRunId": {
            "title": "Resume from a previous run",
            "type": "string",
            "description": "Paste a previous run ID or dataset ID to continue a large crawl without returning or charging for listings already collected there. For recurring monitoring of the same search, use Incremental mode below instead."
          },
          "incrementalMode": {
            "title": "Incremental changes for scheduled runs",
            "type": "boolean",
            "description": "Turn this on for daily or recurring monitoring. The first run returns all matching listings as NEW. Later runs normally return only NEW, UPDATED and REAPPEARED listings. Turn on 'Emit unchanged' or 'Emit expired' only when you also want those rows returned (and billed). State is kept separately for each location, channel, filter and detail setup; use State key when you want to name or deliberately share a monitoring campaign. To continue one specific interrupted run instead, use Resume from a previous run above.",
            "default": false
          },
          "stateKey": {
            "title": "State key (optional, incremental mode only)",
            "type": "string",
            "description": "Optional. Name this monitoring campaign to keep its state stable, or to deliberately share state across differently-configured runs. Leave empty to let the actor derive a key automatically from the location, channel, filters and detail settings, so different searches never mix state with each other."
          },
          "emitUnchanged": {
            "title": "Emit unchanged listings (incremental mode only)",
            "type": "boolean",
            "description": "Off by default. Turn on to also return listings that have not changed since the last run, marked UNCHANGED. This returns, and bills, extra rows you already have, so leave it off unless you specifically want the full snapshot every run.",
            "default": false
          },
          "emitExpired": {
            "title": "Emit expired listings (incremental mode only)",
            "type": "boolean",
            "description": "Off by default. Turn on to also return listings that were present in a previous run but are no longer found, marked EXPIRED. Only produced once a run has fully scanned the tracked search, never when Max items capped it, when Resume was used, or when the run scanned nothing. This returns, and bills, extra synthetic rows, so leave it off unless you need expiry tracking.",
            "default": false
          },
          "proxy": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "homes.com serves its listing pages only to US connections and refuses low-quality exits outright, so this run climbs to a residential US connection as soon as a cheaper one is refused. Apify Proxy works on every plan; leave it enabled for the most reliable results.",
            "default": {
              "useApifyProxy": true
            }
          },
          "mcpConnectors": {
            "title": "Pipe results into your apps (optional)",
            "type": "array",
            "description": "Optionally send the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector once under Apify > Settings > Integrations, then select it here. The connector receives a condensed, human-readable summary per item (title + key fields), not the full JSON: the complete record stays in the dataset. Leave empty to skip."
          },
          "notionParentPageUrl": {
            "title": "Notion parent page (Notion connector only)",
            "type": "string",
            "description": "URL (or id) of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors."
          },
          "maxNotifyListings": {
            "title": "Max items to export per connector",
            "minimum": 1,
            "type": "integer",
            "description": "Cap on items written to each connector per run. Does not affect the dataset.",
            "default": 50
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}