# RealForeclose & RealTaxDeed County Auctions Scraper (`arezdev/us-county-foreclosure-tax-deed-auctions-scraper`) Actor

Extract public RealForeclose and RealTaxDeed auction dockets by county and sale date. Collect case numbers, parcel IDs, judgments, bids and assessed values. Calculate screening estimates and export property records for auction research.

- **URL**: https://apify.com/arezdev/us-county-foreclosure-tax-deed-auctions-scraper.md
- **Developed by:** [Arezdev](https://apify.com/arezdev) (community)
- **Features:** Limited permissions
- **Stats:** 8 total users, 7 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 auction extracteds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

**Turn county foreclosure and tax deed auction dockets into structured property leads with calculated equity spreads and surplus recovery estimates.**

Extract public RealForeclose and RealTaxDeed auction cards for a specific county and sale date. Get case numbers, parcel IDs, addresses, judgments, bids, assessed values, and source links in a flat dataset ready for spreadsheets and automation.

Best for organizing county auction research. Use a sale date present in the portal calendar; dates without auctions can return no rows. Equity and surplus fields are screening calculations from published values, not appraisals or confirmed recoverable funds.

### Ready-to-run example

The Input form includes public example values. A fresh `apify run` uses the input schema defaults. To explicitly select the small sample, including when input was saved by an earlier local run, use:

```sh
apify run --input-file .actor/input.example.json
```

#### Run results and source access

The final status counts successful auctions separately from uncharged ERROR diagnostics. A run containing only diagnostics explicitly reports that no auctions were extracted. On October 22, 2026, direct preview requests to Miami-Dade, Broward, Pinellas, and Palm Beach returned HTTP 403; changing the sample county did not establish direct access. Local runs can use the Apify proxy password supplied by the CLI environment, and custom proxy URLs remain supported. Proxy availability depends on the account and does not guarantee that a portal will accept the connection.

You can also paste [.actor/input.example.json](.actor/input.example.json) into the JSON input editor in Apify Console. Replace the example sources with your own targets and increase the limits when you are ready.

### How to use

1. Select a county auction portal and enter the sale date shown in its public auction calendar.
2. Start with the prefilled maximum of **3 records** to check availability. The API default is **50 records**.
3. Optionally set a minimum equity spread or configure a proxy.
4. Run the Actor and export the dataset as JSON, CSV, Excel, or another Apify export format.

```json
{
  "countyPortal": "miamidade.realforeclose.com",
  "auctionDate": "10/15/2026",
  "minPotentialEquity": 0,
  "maxItems": 3,
  "timeoutSecs": 15
}
```

The example selects the requested default date; it does not guarantee that the county has auctions on that date or that its portal permits a direct connection. A blocked portal produces a useful ERROR record with no `auction-scraped` event fee. An available date with no auctions produces an empty dataset.

### What data can you extract?

| Data | Fields |
| --- | --- |
| County and sale | `countyDomain`, `auctionType`, `auctionDate`, `auctionStatus` |
| Property and case | `caseNumber`, `parcelId`, `propertyAddress`, `city`, `state`, `zipCode`, `plaintiffName` |
| Published amounts in USD | `finalJudgmentAmount`, `openingBid`, `winningBidAmount`, `assessedValue` |
| Screening estimates | `estimatedEquitySpread`, `estimatedSurplusFunds`, `isSurplusRecoveryLead` |
| Traceability | `sourceUrl`, `scrapedAt`, `status`, `errorMessage` |

`estimatedEquitySpread` is assessed value minus final judgment when both published amounts are greater than zero. Otherwise it is `null`.

`estimatedSurplusFunds` is the positive difference between a published winning bid and a known final judgment. Otherwise it is `0`. `isSurplusRecoveryLead` becomes `true` at **$10,000** or more. Currency differences are rounded to cents.

Missing published data stays `null`; hidden bids are never replaced with invented amounts. A plaintiff maximum bid is not treated as an opening or winning bid. Tax deed opening bids and amounts due are not treated as foreclosure final judgments.

These fields screen published auction data. They do not establish market equity, distributable court funds, or eligibility to recover a surplus. Verify the property record, auction outcome, judgment, and clerk's distribution records before acting.

### Input settings

| Setting | Default | Behavior |
| --- | --- | --- |
| `countyPortal` | `miamidade.realforeclose.com` | Select one of the nine supported portals below. |
| `customCountyDomain` | Unset | Optional bare county hostname under `realforeclose.com` or `realtaxdeed.com`; overrides the selection. |
| `auctionDate` | `10/15/2026` | Accepts `MM/DD/YYYY` and `YYYY-MM-DD`; validates real calendar dates. |
| `minPotentialEquity` | `0` | Zero disables filtering. A nonzero threshold requires a known equity spread at least as large as the threshold. Negative thresholds are supported. |
| `maxItems` | `50`; UI prefill `3` | Total saved SUCCESS and ERROR records, from 1 to 2,000. |
| `timeoutSecs` | `15` | Per-route request deadline, from 3 to 60 seconds; includes DNS and redirects. Proxy failover can require multiple routes. |
| `maxConcurrency` | `25` | Worker upper limit from 1 to 100. There are three docket areas; shared-session HTTP requests are serialized to preserve server pagination and proxy affinity. |
| `proxyConfiguration` | Unset | Direct first, then permitted datacenter fallback. See below. |

Supported selections:

- `miamidade.realforeclose.com`
- `broward.realforeclose.com`
- `hillsborough.realforeclose.com`
- `myorangeclerk.realforeclose.com`
- `pinellas.realforeclose.com`
- `duval.realforeclose.com`
- `palmbeach.realforeclose.com`
- `miamidade.realtaxdeed.com`
- `hillsborough.realtaxdeed.com`

#### Proxy behavior

With no proxy setting, the Actor tries a direct connection. On HTTP 403, 429, or 503 it tries Apify SHADER datacenter access, then the account's default datacenter access. An unavailable SHADER group does not stop the run.

Set `proxyConfiguration.useApifyProxy` to `true` to permit a final configured proxy tier. If no groups are provided, that final tier uses `RESIDENTIAL`. Residential access requires this explicit opt-in. Set it to `false` to force direct access. Providing `proxyUrls` forces custom HTTP or HTTPS proxies.

On Apify, automatic proxy access requires the platform-provided proxy configuration and account access. The Actor never fetches a proxy password through the user profile API. Outside Apify, automatic Apify proxy tiers are skipped; custom proxies are supported.

When changing connection routes, the Actor creates a new cookie session and reloads the sale preview before requesting further docket data. Proxy connections use an IP-pinned CONNECT tunnel and HTTP/1.1 while preserving the original hostname for TLS. A proxy must support CONNECT to public IP addresses.

### Output example

Illustrative output showing the field structure and arithmetic, not a real property or court record:

```json
{
  "countyDomain": "miamidade.realforeclose.com",
  "status": "SUCCESS",
  "auctionType": "FORECLOSURE",
  "auctionDate": "10/15/2026",
  "auctionStatus": "Sold to third party",
  "caseNumber": "EXAMPLE-2026-001",
  "parcelId": "EXAMPLE-PARCEL-001",
  "propertyAddress": "123 Example Ave",
  "city": "MIAMI",
  "state": "FL",
  "zipCode": "33101",
  "finalJudgmentAmount": 100000,
  "openingBid": 50000,
  "winningBidAmount": 125000,
  "assessedValue": 200000,
  "estimatedEquitySpread": 100000,
  "estimatedSurplusFunds": 25000,
  "isSurplusRecoveryLead": true,
  "plaintiffName": "Example Bank",
  "sourceUrl": "https://miamidade.realforeclose.com/index.cfm?zaction=AUCTION&zmethod=PREVIEW&AuctionDate=10%2F15%2F2026",
  "scrapedAt": "2026-10-19T12:00:00.000Z",
  "errorMessage": null
}
```

ERROR rows use the same flat schema, preserve the county, date, source URL, and extraction timestamp, and contain a safe public error description. Property fields are `null`, surplus is `0`, and `isSurplusRecoveryLead` is `false`.

### Use the results in Clay, n8n, Make, or your API

- **Clay:** Import the dataset CSV or retrieve JSON with an HTTP integration. Match properties by parcel ID and case number.
- **n8n:** Run the Actor with the Apify integration, wait for completion, and read its dataset items. Route `status === "SUCCESS"` rows into your workflow.
- **Make:** Connect an Apify run completion trigger to dataset retrieval, then filter on the equity or surplus lead fields.
- **API:** Use the Actor's API tab to start a run. Read the returned `defaultDatasetId` and request its dataset items through the Apify Dataset API. Store API credentials in your automation platform's credential manager.

Use `isSurplusRecoveryLead` to create a review queue and `sourceUrl` to open the county record. Use `(countyDomain, auctionDate, caseNumber, parcelId)` as a downstream matching key. Deduplicate across repeated runs in your destination system.

### Pricing and limits

Only saved SUCCESS auction records consume the custom **`auction-scraped`** event. **ERROR rows cost $0 in auction event fees.** Records excluded by the equity filter and duplicate records are not charged this event.

The published Store pricing controls the event rate. For a concrete illustration, at **$0.005 per successful auction**, 1,000 SUCCESS records cost **$5.00** in auction event fees; an additional 100 ERROR rows add **$0.00** in auction event fees. This is a calculation example, not a promised published price. Compute, storage, and proxy costs are governed by your Apify plan and run settings.

Free Apify users can save at most **25 total records per run**, including ERROR rows. Paying users can request up to **2,000** records per run. Local runs have no free-plan restriction and still respect `maxItems`. The Actor stops cleanly when the item or event charge budget is exhausted.

The runtime defaults to **256 MB** and a **3,600-second** run timeout. Records are written in serialized batches of up to 100 or every five seconds. Extraction uses direct HTTP requests without a browser. Each docket area is capped at 2,000 page requests, with repeated pages detected to prevent loops. A run scans at most 100,000 unique cards to bound duplicate tracking memory when an equity filter excludes many auctions. HTTP responses are capped after decompression at 4 MB for HTML, 2 MB for JSON, and 15 MB for XML. Decoded compact docket HTML is also capped at 4 MB.

### FAQ and troubleshooting

#### Why did the run save an ERROR row with HTTP 403 or 429?

The county blocked or rate-limited the connection. The Actor tries permitted proxy routes and preserves a safe diagnostic if they fail. Check your Apify proxy access and explicitly permit the configured final tier when needed. Error rows have no `auction-scraped` fee.

#### Why are there no results?

The selected date may have no auctions, all properties may be excluded by the equity filter, or the docket may have changed. Check the county calendar and try a threshold of zero. An unreadable or malformed docket produces an ERROR row rather than a fabricated property record.

#### Why are some amounts or addresses missing?

Counties publish different card fields. The Actor reports the public docket as supplied; it does not infer undisclosed bids or enrich records from assessor or court detail pages. A published city and ZIP on a second address row are supported.

#### How are waiting, running, and completed sales handled?

The Actor initializes the requested date through the preview page and loads the W, R, and C areas. It requests the AJAX endpoint and supports the UPDATE endpoint as a compatibility fallback. It decodes compact `retHTML` tokens, follows docket pages, and suppresses duplicate auction IDs. Cancelled or postponed status text remains visible when published.

#### Can I use any website as a custom county domain?

Custom domains must belong to the public RealForeclose or RealTaxDeed engine. Internal hosts, non-default target ports, URL credentials, private DNS answers, and unsafe redirects are rejected. JSON export escapes strings normally; spreadsheet formula prefixes are neutralized in text values while numeric amounts remain numbers.

#### Does a timeout discard every recovered record?

Complete HTML prefixes of at least 16 KiB received with a 2xx status can be recovered after a timeout or connection reset. Oversized HTML can also be truncated safely. JSON docket envelopes require complete, valid JSON. Partial recovery is reported in safe run warnings.

#### Is the three-record sample guaranteed to finish in five seconds?

No live county portal can provide that guarantee. The prefill limits the sample to three saved records, but DNS, portal response time, auction availability, and access controls determine its duration. Automated tests use deterministic fixtures; runtime results always come from the selected portal.

### Development

Requires Node.js 22 or later.

```sh
npm ci
npm run build
npm test
npm start
```

For local custom input, save JSON to `storage/key_value_stores/default/INPUT.json` before starting. No environment file is required or loaded by the Actor. `npm test` compiles strict TypeScript and runs the Node test suite with `UV_THREADPOOL_SIZE=64`, production mode, and certificate verification enabled.

```sh
docker build -t county-auctions .
docker run --rm --memory=256m county-auctions
```

The container uses Node.js 22 Alpine, a separate build stage, a non-root user, a 160 MB V8 heap limit, and a 64-thread libuv pool. Shutdown hooks abort active network requests and flush buffered rows.

The dependency lock includes a `basic-ftp` override to version 6.2.3 for the SDK's proxy dependency chain, covering the upstream [directory parser security advisory](https://github.com/patrickjuchli/basic-ftp/security/advisories/GHSA-c475-qrg2-pj4r). This Actor accepts HTTP and HTTPS targets only.

Before publishing, configure pay-per-event monetization in Apify Console with the event name `auction-scraped` and your chosen event price. Use this event as the sole auction output fee so diagnostic ERROR rows remain free of auction event charges. No user-profile permission is required.

Reference: [Apify pay-per-event charging](https://docs.apify.com/sdk/js/reference/class/ChargingManager), [input schema](https://docs.apify.com/actors/development/actor-definition/input-schema/specification/v1), [dataset schema](https://docs.apify.com/storage/dataset-schema).

# Actor input Schema

## `countyPortal` (type: `string`):

The county RealForeclose or RealTaxDeed portal to search.

## `customCountyDomain` (type: `string`):

Optional bare hostname under realforeclose.com or realtaxdeed.com. Overrides the selected county portal. Do not include a URL path or scheme.

## `auctionDate` (type: `string`):

The exact sale date in MM/DD/YYYY or YYYY-MM-DD format. Availability depends on the county calendar.

## `minPotentialEquity` (type: `number`):

Zero disables filtering and retains auctions with unknown equity. Any other value requires a known assessed value and final judgment and keeps spreads at or above the threshold.

## `maxItems` (type: `integer`):

Maximum total SUCCESS and ERROR records to save. Free Apify users are capped at 25 records per run.

## `timeoutSecs` (type: `integer`):

Deadline for a request route, including DNS, redirects, connection, and response streaming.

## `maxConcurrency` (type: `integer`):

Upper limit for docket area workers. This Actor has three areas; requests sharing a county session are serialized to preserve pagination and proxy affinity.

## `proxyConfiguration` (type: `object`):

Optional. Omit for direct access followed by datacenter fallback on 403, 429, or 503. Explicitly enable Apify Proxy to permit the configured or residential final tier. Set useApifyProxy to false to force direct access, or supply HTTP/HTTPS proxy URLs to force custom proxies.

## Actor input object example

```json
{
  "countyPortal": "miamidade.realforeclose.com",
  "auctionDate": "10/15/2026",
  "minPotentialEquity": 0,
  "maxItems": 3,
  "timeoutSecs": 15,
  "maxConcurrency": 25
}
```

# Actor output Schema

## `auctions` (type: `string`):

Flat auction data, equity and surplus estimates, and uncharged error records.

# 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 = {
    "countyPortal": "miamidade.realforeclose.com",
    "auctionDate": "10/15/2026",
    "maxItems": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("arezdev/us-county-foreclosure-tax-deed-auctions-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 = {
    "countyPortal": "miamidade.realforeclose.com",
    "auctionDate": "10/15/2026",
    "maxItems": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("arezdev/us-county-foreclosure-tax-deed-auctions-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 '{
  "countyPortal": "miamidade.realforeclose.com",
  "auctionDate": "10/15/2026",
  "maxItems": 3
}' |
apify call arezdev/us-county-foreclosure-tax-deed-auctions-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,arezdev/us-county-foreclosure-tax-deed-auctions-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/Nfea5wpUOsDDwlv2y/builds/2uuNdt97Kh5o5Bs2O/openapi.json
