# Copart Intelligence (`gallant_illustration/auction-intelligence`) Actor

Real-time Copart auction monitor. Filter by make, model, year, damage type, yard, sale date, fuel/drive/body, source (repos/theft recovery). New & updated lots streamed to your webhook or Apify Dataset. Pay-per-lot — $0.05 per new, $0.02 per update.

- **URL**: https://apify.com/gallant\_illustration/auction-intelligence.md
- **Developed by:** [Alexei Pannicov](https://apify.com/gallant_illustration) (community)
- **Categories:** E-commerce, Lead generation, Automation
- **Stats:** 3 total users, 1 monthly users, 55.6% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 1,000 new lot founds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Copart Intelligence — Lot Monitor

Get notified about new and updated lots on Copart matching your filter, before others do.

> 💸 **You pay only for *new* and *changed* lots — never for the same listing twice.**
> Each filter keeps its own memory across runs. A lot is charged once when first found (`lot_new`, $0.05), and again only if its price/condition later changes (`lot_updated`, $0.02). Re-running the same filter costs **nothing** for lots that haven't changed — unlike per-row scrapers that re-bill the entire result list on every single run. Set `includeUpdated: false` to pay for new lots only.

This Actor watches Copart's public auction listings on a schedule you control, applies the filter you configure (make, year, damage type, yard, condition), and emits each matching lot to an Apify Dataset and/or your own HTTPS webhook. You pay only for lots the Actor delivers — not for compute minutes or proxy bandwidth.

---

### What this Actor does

- **Crawls Copart's public listing API** through Apify Proxy with real-browser TLS fingerprint, headers, and JS-challenge handling.
- **Detects new lots and price/condition changes** by hashing each lot's canonical field set; previous hashes are persisted in the Actor's KV store, so subsequent runs only surface deltas — no duplicate alerts.
- **Outputs to Apify Dataset and/or your webhook.** Webhook deliveries are HMAC-SHA256 signed (when you provide a secret), sent with up to 3 attempts (1s, 2s backoff), and queued to a per-filter DLQ if all attempts fail.
- **Pay only for results, not compute.** Two pay-per-event prices: `lot_new` and `lot_updated`. Empty runs cost only the standard `apify-actor-start` event (~$0.00005 — effectively free).

---

### Example use cases

- **"All 2018-2024 BMW with minor damage at the TX Dallas yard"** — hourly, posts each match to Slack via webhook.
- **"Toyotas under 80,000 mi, clean title"** — every 4 hours, dataset only.
- **"All Tesla salvage titles in the US"** — daily, fed to a custom dashboard via webhook.

---

### Why monitor Copart in real-time?

Copart processes hundreds of thousands of lots monthly across ~220 yards in the US and Canada. For dealers and resellers, daily manual browsing misses deals — competitors find them first. This Actor solves three concrete problems:

- **Deal hunting**: catch lots matching your specific criteria (make + budget + yard + damage) within minutes of Copart adding them.
- **Multi-yard tracking**: monitor 50+ yards in parallel — impossible with manual browsing.
- **Pipeline automation**: webhook delivery integrates directly with your CRM, bidding tool, Slack, or spreadsheet — no intermediate dashboard needed.

---

### Getting started

1. **Click "Run" or "Start"** at the top of this page.
2. **Configure your filters**:
   - Pick vehicle makes from the dropdown (BMW, Toyota, etc.) or type custom brand names (e.g. `LUCID`, `RIVIAN`).
   - Set year / odometer / vehicle type / body style / fuel / drive train / damage codes.
   - Choose location: pick US states / Canadian provinces (`["TX", "CA"]`) — auto-expands to every Copart yard in those states — or specific yards from the dropdown (271 options — 55 states/provinces + 216 yards).
   - Set a sale-date window via quick preset (`next_7_days`) or custom from/to dates.
3. **Pick output format**: `compact` (default — full buyer detail), `full` (adds damage photos + thumbnail + seller), or `minimal` (headline fields only).
4. **(Optional) Set a webhook** in `webhookUrl` + `webhookSecret` to receive each lot in your own system.
5. **Run** — first run on a fresh filter takes 30-90s, subsequent runs 10-30s.

Each filter has its own state. Run twice with identical input → second run only emits *changed* lots, doesn't re-charge for unchanged ones.

---

### Pricing

**Pay-per-event — and only for deltas.** Thanks to per-filter memory, a lot is billed when it's first found or when it changes, and **never again while it stays unchanged**. There's no per-row re-billing on repeat runs: monitoring a 500-lot filter hourly costs just a handful of delta charges per run after the first — not 500 charges every time. That's the core difference from per-result scrapers that re-charge for the whole list on every run.

The two events you pay for:

| Event          | Price    | When charged                                                                                 |
| -------------- | -------- | -------------------------------------------------------------------------------------------- |
| `lot_new`      | **$0.05** | A lot the Actor has never seen in this filter's history is found.                            |
| `lot_updated`  | **$0.02** | A lot already seen in this filter's history shows a different content hash (price, condition, etc.). Set `includeUpdated: false` in input to opt out and pay only for new lots. |

#### Typical cost scenarios

| Workload | First run | Subsequent runs (deltas only) |
|---|---|---|
| **Narrow** filter — one yard, specific make/year | $0.50 - $2 (10-40 new lots) | $0.05 - $0.25 (1-5 deltas) |
| **Medium** filter — one state, 2-3 makes | $2.50 - $10 (50-200 lots) | $0.25 - $1.50 (5-30 deltas) |
| **Broad** filter — multi-state, no make/damage limit | $10 - $50 (200-1000 lots) | $1.50 - $5 (30-100 deltas) |

**Empty runs** (filter matches nothing today) = **$0.00005** (the standard `apify-actor-start` event charge that fires once per Actor start, regardless of outcome). Practically rounds to zero.

#### Cost control

- **`maxResultsPerRun: 100`** — hard cap on rows per run. Default 500, max 10000. Use 100 on first run with a broad filter to protect against unexpected charges.
- **`includeUpdated: false`** — only pay for `lot_new` events, never for `lot_updated`. Useful when you only care about *fresh* listings.
- **`ACTOR_MAX_TOTAL_CHARGE_USD`** — standard Apify env var. Actor checks it on every charge and exits cleanly when budget is reached.

> **Apify subscription credits** (Free / $49 Starter / $499 Scale plans) apply platform-wide across **all** Actors you run, not just this one. See the [Apify pricing page](https://apify.com/pricing) for the full subscription model. The per-event prices above ($0.05 / $0.02) are what this Actor charges per matching lot — they're billed against your Apify usage like any other PPE Actor.

---

### Input

All filter fields are optional. Empty input means "every active lot Copart is showing right now" — useful for discovery, but expect a large first run.

Common fields:

**Filter — what to monitor**

| Field             | Type                       | Purpose                                                                                  |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| `makes`           | `string[]`                 | Hybrid dropdown — top 40 Copart brands suggested (BMW, Toyota, ...) + you can also type custom make names (Lucid, VinFast, classics). Case-sensitive for custom entries. |
| `models`          | `string[]`                 | Free-text models. Best combined with `makes` to avoid name collisions ("1500" exists for Chevy + RAM). |
| `yearMin`/`yearMax` | `integer`                | Inclusive year range. Either bound is optional.                                          |
| `odometerMax`     | `integer`                  | Upper bound on miles.                                                                    |
| `vehicleTypes`    | `enum[]`                   | Multi-select — "Automobiles", "Motorcycles", "RVs", etc. 15 types.                       |
| `titleGroups`     | `enum[]`                   | "Clean Title", "Salvage", "Nonrepairable".                                               |
| `damageCodes`     | `enum[]`                   | 25 Copart damage categories — "Front End", "Hail", "Minor Dent / Scratches", "Water / Flood", "Rollover", and more. |
| `sources`         | `enum[]`                   | Why the vehicle is at Copart — Donated / Fleet / Impound / Repossession / Theft Recovery / Water-Flood. |
| `fuelTypes`       | `enum[]`                   | Powertrain — Gas / Diesel / EV / Hybrid / Flex Fuel / Hydrogen / CNG.                    |
| `driveTrains`     | `enum[]`                   | FWD / RWD / AWD / 4×4 (front-based) / 4×4 (rear-based) / 4×2 (truck). Aliases handled.    |
| `bodyStyles`      | `enum[]`                   | Sedan / SUV / Pickup / Hatchback / Coupe / Convertible / Wagon / Vans / Cab-Chassis / Cutaway. |
| `location`        | `enum[]`                   | Single location filter — pick US states / Canadian provinces (entire state, auto-expands to all yards there) **and/or** specific yards, in one multi-select. Mix freely — any match is included (union). Example: "Texas — all yards" + "CA - Vallejo". 271 options (55 states + 216 yards). Note: the Washington DC yard is filed under Maryland (MD) — there's no standalone "DC" state option. |
| `runsAndDrivesOnly` | `boolean`                | Only lots with the `Run and Drive` (`CERT-D`) condition.                                |
| `engines`         | `string[]` (free-text)     | Engine description (e.g. `2.0L 4`, `3.0L 6`, `5.0L 12` — one space before the cylinder count). ⚠️ Case- and space-sensitive — copy verbatim from Copart's Engine facet. Multiple selections OR'd. |
| `transmissions`   | `enum[]`                   | `AUTOMATIC` / `MANUAL`. BMW-verified; CVT added later if broader-make probe confirms.    |
| `cylinders`       | `enum[]`                   | Cylinder count: `0` (EV) / `3` / `4` / `6` / `8` / `10` / `12`. Field is string-typed in Copart's Solr — schema enforces strings. |
| `colors`          | `string[]` (free-text)     | Exterior color (e.g. `GRAY`, `BLACK`, `WHITE`). ⚠️ Case-sensitive UPPERCASE. **Capability beyond Copart UI parity** — Copart's UI doesn't expose color filter, but the field is filter-usable. |
| `saleDatePreset`  | `enum`                     | Quick window: `today` / `tomorrow` / `next_7_days` / `next_30_days`. Wins over custom dates.  |
| `saleDateFrom`/`saleDateTo` | `string` (YYYY-MM-DD) | Custom date window. Ignored if `saleDatePreset` is set. UTC.                       |

**Filter — inventory features**

| Field             | Type                       | Purpose                                                                                  |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| `features`        | `enum[]`                   | Copart UI "Featured items" sidebar toggles — multi-select OR'd. Values: `used`, `no_license_required`, `hot_items`, `featured_vehicles`, `offsite_sales`, `engine_start`, `enhanced`, `classics`, `inspected`, `public_and_general_business`, `bank_repossessed`, `pure_sale`. Some Featured items live in dedicated fields above (Buy It Now / Run and Drive / Electric/Hybrid / Recovered Thefts / Fleet & Lease). |
| `newlyAddedWithinDays` | `integer` (1–30)      | Filter to lots added to Copart inventory within last N days (range 1–30). Common presets: `1` (last 24h), `7` (last week), `30` (last month). Distinct from `saleDatePreset` — this is inventory-add date, not auction date. |
| `classicsYearsOld` | `integer` (1–100)         | Override the 25-year default Classics threshold. Only applies when `features` includes `classics`. |

**Filter — auction state**

| Field             | Type                       | Purpose                                                                                  |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| `salePlatforms`   | `enum[]`                   | Include only specific Copart sale platforms (`CPRTUSA` / `PWUSA` / `NCS`). Leave empty to include all. |
| `excludeSalePlatforms` | `enum[]`              | Exclude specific platforms — typical use: exclude Purple Wave (PWUSA) which has higher buyer fees. Cannot overlap with `salePlatforms`. |
| `excludeOnApproval` | `boolean`                | Skip lots that require seller approval (`On Approval` status). Equivalent to Copart UI's "Pure Sale Items" filter. |

**Filter — price & budget**

| Field             | Type                       | Purpose                                                                                  |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| `currentBidMin`   | `integer` (USD)            | Lowest current bid to include (inclusive). ⚠️ **Client-side filter** — see caveat below. |
| `currentBidMax`   | `integer` (USD)            | Highest current bid to include (inclusive). Pre-bid lots (no current bid) are treated as $0. |
| `buyItNowOnly`    | `boolean`                  | Only lots with a Buy It Now price (~4.4% of inventory). Server-side filter — no extra fetch cost. |

> ⚠️ **Client-side filtering caveat** (applies to `currentBidMin` / `currentBidMax`):
> Copart's API does **not** expose a server-side current-bid filter. To apply the range, this Actor fetches **up to 3× more pages** from Copart per run and discards off-range lots before they're charged. Net effect:
> - **PPE cost is unaffected** — you only pay per matching lot, not per fetched lot.
> - **Run wall-clock can be 2-3× longer** for narrow price bands.
> - Very narrow bands (`max - min < 1000` on a broad search) may hit the page cap before finding enough matching lots — narrow your `makes` / `models` filter instead.

**Search by identifier (advanced)**

| Field             | Type                       | Purpose                                                                                  |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| `vin`             | `string` (17 chars)        | Look up by Vehicle Identification Number. Regex `^[A-HJ-NPR-Z0-9]{17}$` (excludes I/O/Q). Combines with bucket filters via AND. |
| `lotNumbers`      | `string[]` (digits)        | Look up a specific lot by its 8-digit number. Phase 1 supports a single lot per run; multi-lot lookup is a Phase 2 enhancement. |
| `freeFormQuery`   | `string`                   | Full-text keyword search across lot fields. Multi-token AND. Example: `low miles BMW`.   |

> ⚠️ **Mutual exclusion**: at most one of `vin`, `lotNumbers`, `freeFormQuery` may be set per run — they all map to Copart's single search-text slot. The Actor rejects input with multiple identifier fields. Combining an identifier with **other** filters (makes, years, states, etc.) is fully supported and AND'd at the Solr layer.

**Delivery (optional)**

| Field             | Type                       | Purpose                                                                                  |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| `webhookUrl`      | `string` (URL)             | If set, each emitted lot is POSTed to this URL.                                          |
| `webhookSecret`   | `string` (secret)          | HMAC-SHA256 secret. Apify encrypts this at rest.                                         |

**Run behavior**

| Field             | Type                       | Purpose                                                                                  |
| ----------------- | -------------------------- | ---------------------------------------------------------------------------------------- |
| `maxResultsPerRun` | `integer` (default 500)   | Hard cap on lots per run. Protects against runaway charges on broad filters.             |
| `includeUpdated`  | `boolean` (default `true`) | Emit `lot_updated` events; set `false` to pay only for `lot_new`.                        |
| `outputFormat`    | `enum`                     | `compact` (default — full buyer detail), `full` (adds damages[] + thumbnail + seller + ldu), `minimal` (lot id + vehicle + bid + odometer + primary damage + title + location).      |
| `sortBy`          | `enum`                     | Sort order, mirroring Copart's UI "Sort by" dropdown: `auction_date` / `odometer` / `year` / `make` / `model` / `item_number` / `buy_it_now` / `current_bid` / `sale_light`. Leave empty for Copart's default (sale-light priority). "Location distance" (nearest ZIP) coming in a future release. |

---

### Output

Each lot is written as a single row to the default Apify Dataset, plus optionally posted to your webhook.

#### Dataset row example (`outputFormat: "compact"` — default)

```json
{
  "_metadata": {
    "ref": "apify-actor",
    "isNew": true,
    "captured_at": "2026-05-17T10:42:13.383Z",
    "lotHash": "EHrBVqBcfT/NCPtyC03YPvtQZcRgVf6TnDXxpa2Bh1I=",
    "lastUpdatedMs": 1778866098000
  },
  "lotNumber": 95786325,
  "make": "TOYOTA",
  "model": "CAMRY",
  "year": 2022,
  "currentBid": 3100,
  "odometer": 66119,
  "primaryDamage": "MINOR DENT/SCRATCHES",
  "titleGroup": "CLEAN TITLE",
  "yardName": "TX - DALLAS SOUTH",
  "locationState": "TX",
  "description": "2022 TOYOTA CAMRY SE",
  "vehicleType": "AUTOMOBILE",
  "vin": "4T1G11AK4NU******",
  "saleDateUtc": "2026-05-18T16:00:00.000Z",
  "secondaryDamage": null,
  "titleType": "CERTIFICATE OF TITLE",
  "color": "CHARCOAL",
  "driveTrain": "Front-wheel Drive",
  "fuelType": "GAS",
  "engine": "2.5L 4",
  "cylinders": "4",
  "runCondition": "RUNS AND DRIVES",
  "hasKeys": "YES",
  "odometerBrand": "ACTUAL",
  "inspected": true,
  "buyItNowPrice": 0,
  "buyItNowAvailable": true,
  "carfaxAvailable": false,
  "saleBrand": "COPART",
  "currency": "USD",
  "locationCountry": "USA"
}
````

`outputFormat: "full"` adds the per-panel `damages[]` array (with image URLs), `thumbnailUrl`, `seller`, and the Copart lot slug `ldu`. `outputFormat: "minimal"` keeps only `_metadata`, `lotNumber`, `make`, `model`, `year`, `currentBid`, `odometer`, `primaryDamage`, `titleGroup`, `yardName`, `locationState`.

> **Trim**: `description` carries the full vehicle description including trim (e.g. "CAMRY **SE**") — the trim isn't in the separate make/model/year fields.

> **Damage**: `primaryDamage` is the headline summary and is populated even for freshly-listed lots. The detailed per-panel `damages[]` array (full format) is filled in only after Copart's inspection — it may be empty for very fresh lots.

***

### Webhook delivery

Each emitted lot is `POST`ed to your `webhookUrl` with `Content-Type: application/json`. Headers:

| Header                              | Value                                                                              |
| ----------------------------------- | ---------------------------------------------------------------------------------- |
| `User-Agent`                        | `CopartIntelligence-Apify/1.0`                                                     |
| `X-CopartIntelligence-Delivery-Id`  | Unique UUID per delivery — dedup key on the receiver side.                         |
| `X-CopartIntelligence-Signature`    | `sha256=<hex>` — present only when `webhookSecret` is set. HMAC-SHA256 of body.    |

Retry policy: 3 attempts per delivery with exponential backoff (1s, 2s). HTTP 410 Gone = endpoint disabled — silent skip, no retry. Other non-2xx / network errors → per-filter DLQ, retried at the start of the next run. After 5 consecutive failed retry rounds on the same queued delivery (on top of the initial 3-attempt send), the Actor sets `webhookDisabled` in KV and skips webhooks until you clear that flag in Apify Console.

#### Webhook payload example

```json
{
  "event": "lot.alert",
  "alert_type": "new",
  "lot": {
    "_metadata": {
      "ref": "apify-actor",
      "isNew": true,
      "captured_at": "2026-05-17T10:42:13.383Z",
      "lotHash": "EHrBVqBcfT/NCPtyC03YPvtQZcRgVf6TnDXxpa2Bh1I=",
      "lastUpdatedMs": 1778866098000
    },
    "lotNumber": 95786325,
    "make": "TOYOTA",
    "model": "CAMRY",
    "year": 2022,
    "currentBid": 3100,
    "odometer": 66119,
    "primaryDamage": "MINOR DENT/SCRATCHES",
    "titleGroup": "CLEAN TITLE",
    "yardName": "TX - DALLAS SOUTH",
    "locationState": "TX",
    "description": "2022 TOYOTA CAMRY SE",
    "vehicleType": "AUTOMOBILE",
    "vin": "4T1G11AK4NU******",
    "saleDateUtc": "2026-05-18T16:00:00.000Z",
    "secondaryDamage": null,
    "titleType": "CERTIFICATE OF TITLE",
    "color": "CHARCOAL",
    "driveTrain": "Front-wheel Drive",
    "fuelType": "GAS",
    "engine": "2.5L 4",
    "cylinders": "4",
    "runCondition": "RUNS AND DRIVES",
    "hasKeys": "YES",
    "odometerBrand": "ACTUAL",
    "inspected": true,
    "buyItNowPrice": 0,
    "buyItNowAvailable": true,
    "carfaxAvailable": false,
    "saleBrand": "COPART",
    "currency": "USD",
    "locationCountry": "USA",
    "damages": [
      {
        "itemDescription": "Front Bumper",
        "damageDescription": "Heavy Scratch",
        "severityDescription": "3 To 4 Inches",
        "combinedDescription": "Front Bumper, Heavy Scratch, 3 To 4 Inches",
        "damageArea": "OTHER",
        "detectionArea": null,
        "imageUrl": "https://c-static.copart.com/.../8299414a46e747fb96aa576a9475c915_hrs.jpg",
        "thumbnailUrl": "https://c-static.copart.com/.../8299414a46e747fb96aa576a9475c915_thb.jpg"
      }
    ],
    "thumbnailUrl": "https://cs.copart.com/v1/AUTH_svc.pdoc00001/lpp/1225/72b41288_thb.jpg",
    "seller": "HOLMAN",
    "ldu": "clean-title-2022-toyota-camry-se-tx-dallas-south"
  },
  "delivered_at": "2026-05-17T10:42:13.384Z",
  "delivery_id": "40c3c175-6134-4a2a-91f2-164ebc155f5c"
}
```

This example shows the **full** outputFormat. The `lot` field shape matches your `outputFormat` input: `full` adds the per-panel `damages[]` array + `thumbnailUrl` + `seller` + `ldu` on top of compact; `compact` (default) carries the full flat buyer detail (odometer, damage, title, color, drivetrain, run condition, keys, …); `minimal` keeps the headline fields (`lotNumber`/`make`/`model`/`year`/`currentBid`/`odometer`/`primaryDamage`/`titleGroup`/`yardName`/`locationState`) + `_metadata`. Pick `compact` to reduce webhook bandwidth.

#### Signature verification (Node.js)

```js
const crypto = require('node:crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !signatureHeader.startsWith('sha256=')) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  // `timingSafeEqual` requires equal-length buffers; fall back to false otherwise.
  const a = Buffer.from(signatureHeader);
  const b = Buffer.from(expected);
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

// Test vector — match this exactly to confirm your verifier works:
//   body    = '{"hello":"world"}'
//   secret  = 'topsecret'
//   signature = 'sha256=afd00617ceb8f63e65ea5c310f06bf78c3901e7a713db532e25da26ad63c7236'
```

#### Signature verification (Python)

```python
import hmac, hashlib

def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    if not signature_header.startswith("sha256="):
        return False
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header, expected)
```

Always pass the **raw** request body bytes (not a parsed/re-serialized JSON object) into the HMAC — any whitespace difference breaks the signature.

***

### Scheduling

Set the run cadence in Apify Console → Schedules. Recommended starting points:

- **Hourly** — active buyers tracking specific makes/yards. Typical cost: $1–$5/day on a narrow filter.
- **Every 15 minutes** — serious users on time-sensitive auctions. Higher cost; check `maxResultsPerRun` against your daily budget.
- **Daily** — browsing or weekly-priced lots. Lowest cost.

The Actor uses a per-filter lock so two concurrent runs of the same filter (e.g. an accidental double-trigger) don't double-charge — the second run exits cleanly with a "previous run still active" status message.

***

### Tips for getting the most out of this Actor

- **Start narrow, broaden later** — first run with one yard + one make. Once you trust the filter, expand to a state or multiple makes. Helps you calibrate `maxResultsPerRun` budget against real inventory volumes.
- **Use a state code in `location`** for state-wide monitoring — picking `"TX"` auto-expands to all 18 TX yards. Cleaner than listing each yard. Mix with specific yard slugs in the same field if you want a state plus a yard from elsewhere.
- **Combine `sources: ["repossession", "theft_recovery"]`** for repossessions + theft recoveries — often the cleanest lots with minimal damage. Pair with `damageCodes: ["minor_dent"]` (Minor Dent) for inventory you can flip without bodywork.
- **`outputFormat` controls both Dataset and webhook payload verbosity**. `compact` (default) carries the full flat buyer detail without the heavy per-panel damages array; use `full` if your receiver wants the `damages[]` array + thumbnail + seller + `ldu`; use `minimal` for the headline fields only (lot, vehicle, bid, odometer, primary damage, title, location).
- **Cap `maxResultsPerRun: 100`** on your first run with a broad filter — protects against unexpected $25+ charges while you're still calibrating.
- **Schedule cadence matches your responsiveness** — if you check Slack hourly, schedule hourly. Daily checkers should schedule daily — no point paying for `lot_updated` events you won't react to. Set `includeUpdated: false` if you're a daily checker who only cares about *new* listings.
- **Treat `webhookSecret` like an API key** — Apify encrypts it at rest via `isSecret: true`, but it's your responsibility to verify HMAC signatures on every webhook to prevent forgery. See [Signature verification](#signature-verification-nodejs) above.

***

### FAQ

**Do I need a Copart account?** No. The Actor reads only Copart's public listing data.

**How fresh is the data?** As fresh as the cadence you set — each run hits Copart in real time, no internal cache.

**Only new lots, never updates?** Set `includeUpdated: false`. Only `lot_new` events are charged.

**Only BMWs in Texas?** Set `makes: ["BMW"]` and `location: ["TX"]` — all TX yards are picked automatically. Or pick specific yards: `location: ["tx_houston", "tx_dallas"]`. You can mix: `location: ["TX", "ca_vallejo"]` = all of Texas plus that one California yard.

**Only BMW X5 specifically?** Set `makes: ["BMW"]` and `models: ["X5"]`. Make+model combined avoids cross-make name collisions (e.g. "1500" exists for both Chevy and RAM).

**Only auctions this week?** Set `saleDatePreset: "next_7_days"`. Or use custom `saleDateFrom: "2026-06-01"` + `saleDateTo: "2026-06-07"`. Preset wins if both set.

**Only repos or theft-recovery (often clean cars)?** Set `sources: ["repossession", "theft_recovery"]`.

**Only EVs?** Set `fuelTypes: ["electric", "electric_and_gas_hybrid"]`.

**Only AWD or 4×4 in snowy markets?** Set `driveTrains: ["awd", "4x4_front", "4x4_rear"]`. Aliases are handled — picking `fwd` matches both `FRONT WHEEL DRIVE` and `Front-wheel Drive` underneath.

**Only SUVs / sedans / pickups?** Set `bodyStyles: ["suv", "pickup"]`. Copart's body-style data is noisy (59 raw variants), but our 12 canonical options absorb all the typo / variant spellings.

**Filter by engine size (e.g. only V6+)?** Set `engines: ["3.0L 6", "4.4L 8", "5.0L 12"]`. ⚠️ Free-text + case- and space-sensitive — must match Copart's exact spelling. Engine descriptions look like `<displacement>L <cylinders>` with one space before the cylinder count (e.g. `2.5L 4`). Likely thousands of variants — copy a known canonical string verbatim from Copart's UI Engine facet. Multiple selections OR'd.

**Filter by transmission (Automatic / Manual only)?** Set `transmissions: ["MANUAL"]` if you want manual-only inventory (~3% of BMW; varies by make). BMW-verified values; CVT may be added in a future release.

**Filter by cylinders (e.g. only 6-cyl and 8-cyl)?** Set `cylinders: ["6", "8"]`. Values are strings (Copart's Solr field is string-typed). EVs are `"0"` (no cylinders) — handy if you want to filter out pure electric.

**Filter by exterior color (e.g. only black or white)?** Set `colors: ["BLACK", "WHITE"]`. ⚠️ Case-sensitive UPPERCASE — must match Copart's canonical spelling (`GRAY`, `SILVER`, `MAROON`, etc.). This field is **not in Copart's UI sidebar** — this Actor exposes it as an advanced capability beyond Copart UI parity.

**Find lots added in last 24 hours?** Set `newlyAddedWithinDays: 1`. Useful for daily-check schedules where you only want today's fresh inventory. Range is 1–30 days. Note: this is when the lot APPEARED in Copart's inventory, not when its auction runs (use `saleDatePreset` for that).

**Only Hot Items / Featured Vehicles / Offsite Sales?** Set `features: ["hot_items"]` (or any combination — multi-select OR'd). Each value maps to a Copart UI "Featured items" sidebar toggle. Some Featured items (Buy It Now, Run and Drive, Electric, Hybrid, Recovered Thefts, Fleet/Lease) live in dedicated fields above for cleaner UX.

**Only Inspected lots (Copart-certified inspection)?** Set `features: ["inspected"]`. Copart's UI uses an opaque compound predicate behind this toggle (Copart-internal seller list + flag check) — this Actor replicates the exact predicate Copart's UI sends.

**Only Bank/Repossessed inventory?** Set `features: ["bank_repossessed"]`. Tighter than just `sources: ["repossession"]` — this also requires the lot to have Copart's `blucar_flag:true` set, which is the same predicate the UI's "Bank/Repossessed" toggle uses.

**Only classic cars (≥ 25 years old)?** Set `features: ["classics"]`. To customize the threshold (e.g. 15 years), also set `classicsYearsOld: 15`. Uses Solr date-math `lot_year_date:[* TO NOW/YEAR-NYEARS]` so the cutoff updates automatically as years pass.

**Public / General Business sellers only (vs insurance)?** Set `features: ["public_and_general_business"]`. Mirrors Copart's "Public and General Business" UI toggle — opaque seller-number compound replicated verbatim.

**Why exclude On Approval lots?** Lots marked `On Approval` require the seller to approve the winning bid post-sale — they often don't actually sell at first auction. Dealers who want lots that **will** transact on sale day set `excludeOnApproval: true`. This is equivalent to Copart UI's "Pure Sale Items" Featured filter.

**Why exclude Purple Wave (PWUSA)?** Purple Wave is a partner platform on Copart with **higher buyer fees** than standard Copart USA lots. Dealers optimizing for margin often exclude it: `excludeSalePlatforms: ["PWUSA"]`. Include only `CPRTUSA` if you want strictly Copart-direct inventory.

**Filter by budget (e.g. lots under $5000)?** Set `currentBidMax: 5000`. ⚠️ This is a **client-side filter** — Copart's API doesn't expose price as a server-side filter, so this Actor fetches up to 3× more pages and trims off-range lots after fetching. **PPE cost is the same per matching lot**, but a run with a narrow price band can take 2-3× longer. Combine with `makes`/`models` for tighter filtering and faster runs.

**Filter by exact budget range (e.g. between $1000 and $5000)?** Set both `currentBidMin: 1000` and `currentBidMax: 5000`. Bounds are inclusive. Pre-bid lots (no current bid yet, effectively $0) are kept when `currentBidMin` is 0 or unset.

**Only Buy It Now lots (skip auction-only)?** Set `buyItNowOnly: true`. About 4.4% of Copart inventory has a Buy It Now price — useful for dealers who want predictable instant-buy pricing without bidding wars. No extra fetch cost (server-side filter).

**Look up a specific VIN?** Set `vin: "5UX53DP02N9F12345"` — Copart returns matching lots (usually 0 or 1). VINs are 17 chars, A-Z/0-9 excluding I/O/Q. Combine with `makes: ["BMW"]` to assert "this VIN should be a BMW" — if the lot exists but isn't a BMW, you get zero results.

**Find a specific lot by number?** Set `lotNumbers: ["12345678"]`. Phase 1 supports a single lot per run; multi-lot lookup is a Phase 2 enhancement. Lot numbers are typically 8 digits — find them in Copart listing URLs (`/lot/12345678/...`).

**Free-form keyword search?** Set `freeFormQuery: "low miles"` — Copart's Solr does a full-text search across description, make, model, and other lot fields. Multi-token AND. Combine with bucket filters for narrower scope. ⚠️ Only one of `vin` / `lotNumbers` / `freeFormQuery` may be set per run — they all share Copart's single search-text slot.

**My brand isn't in the dropdown?** The `makes` field is a hybrid dropdown — just type the brand name (e.g. "LUCID", "RIVIAN") and it'll be passed through to Copart. Case-sensitive — verify exact spelling at the [Copart search page](https://www.copart.com/lotSearchResults) (click "Make" filter to see Copart's own canonical names).

**Why `lot_updated` events on the first run?** A fresh filter starts with an empty KV → everything is `lot_new`. If you see `lot_updated` instead, the same filter input was run before and persisted state. Change one input field (new filter hash, fresh state) or clear `copart-state-<hash>` in Apify Console.

**Webhook is down — what happens?** Up to 3 attempts (initial + 2 retries, 1s then 2s backoff) on the failed delivery, then DLQ; next run replays each queued delivery once. After 5 consecutive failed retry rounds on the same queued delivery, `webhookDisabled: true` is set in KV and webhooks pause until you clear it. Dataset output is independent and keeps working.

**Run multiple filters in parallel?** Yes — different input shapes produce different filter hashes, each with its own KV namespace.

**When will I see results?** First run on a narrow filter: 30–90s. Subsequent runs: 10–30s.

**Affiliated with Copart?** No. Independent third-party tool reading public listings.

***

### Limits and caveats

- **Solr enum coverage**: all 25 `damage_type_code` + 3 `title_group_code` + 15 `vehicle_type_code` values are exposed in the input — extracted from Copart's own search-results facet response (last refresh 2026-05-17). Missing rare codes — file an Issue.
- **Yards reference data**: 216 yards (207 US + 9 Canada) captured 2026-05-17 from Copart's `referenceData/graph` endpoint. The static seed is refreshed quarterly. Brand-new yards appear when we re-capture.
- **No lifecycle transitions**: the Actor emits `lot_new` / `lot_updated` only — `sold` / `withdrawn` terminals are not surfaced in this version.

***

Full canonical Lot shape and field provenance: [08-apify-actor.md](https://github.com/AlexeiPannicov/auction-intelligence/blob/main/docs/architecture/08-apify-actor.md).

# Actor input Schema

## `makes` (type: `array`):

Pick from top 40 Copart brands by inventory OR type a custom make name (Lucid, VinFast, classic / specialty — anything not in the dropdown). Case-sensitive — verify exact spelling at the [Copart search page](https://www.copart.com/lotSearchResults). Note: some brands appear in both full + abbreviated forms (CHEV/CHEVROLET, NISS/NISSAN) — for full coverage of that brand, pick both. Pick multiple — any match is included.

## `models` (type: `array`):

Vehicle models, e.g. X5, CAMRY, F-150. Case-sensitive. Best combined with `Makes` to avoid cross-make collisions (e.g. "1500" exists for both Chevrolet and RAM). Verify spelling at the [Copart search page](https://www.copart.com/lotSearchResults) — click 'Model' filter.

## `yearMin` (type: `integer`):

Inclusive lower bound on the lot year. Leave empty for no lower bound.

## `yearMax` (type: `integer`):

Inclusive upper bound on the lot year. Leave empty for no upper bound.

## `odometerMax` (type: `integer`):

Upper bound on miles. Leave empty for no upper bound.

## `vehicleTypes` (type: `array`):

Filter by vehicle type. Pick multiple — any match is included.

## `titleGroups` (type: `array`):

Filter by title group. Pick multiple — any match is included.

## `damageCodes` (type: `array`):

Filter by primary damage. Pick multiple — any match is included. All 25 damage categories Copart offers are supported.

## `location` (type: `array`):

Pick US states / Canadian provinces (entire state — auto-expands to every Copart yard there) and/or specific yards. Mix freely — any match is included (union). Example: pick "Texas — all yards" plus "CA - Vallejo" to monitor all of Texas plus that one California yard. Leave empty to search all locations. Note: the Washington DC yard is grouped under Maryland (MD) — picking "Maryland — all yards" includes it.

## `sources` (type: `array`):

Why the vehicle ended up at Copart. Pick multiple — any match is included. Repos and theft recovery often = clean cars with minimal damage; donations / impounds vary widely.

## `fuelTypes` (type: `array`):

Filter by powertrain. EV / hybrid / diesel each have distinct resale dynamics. Pick multiple — any match is included. Note: Copart stores several hybrid spellings as separate values — to catch every hybrid, pick all three Hybrid options; likewise pick both Flexible options for full E85 coverage.

## `driveTrains` (type: `array`):

Drive train. Each option covers Copart's different spellings for that drive type (e.g. FWD matches every front-wheel-drive spelling). Pick multiple — any match is included.

## `bodyStyles` (type: `array`):

Body style. Each option covers Copart's many spelling variants for that style. Pick multiple — any match is included.

## `runsAndDrivesOnly` (type: `boolean`):

If true, only lots marked 'Run and Drive' are included.

## `engines` (type: `array`):

Filter by engine description. Free-text; multi-word OK (e.g. `2.0L 4`, `3.0L 6`, `4.4L 8`, `5.0L 12` — one space before the cylinder count). ⚠️ Case- and space-sensitive — copy the string verbatim from Copart's Engine facet (a spelling/spacing mismatch silently matches nothing). Copart has thousands of distinct engine descriptions. Pick multiple — any match is included.

## `transmissions` (type: `array`):

Filter by transmission type — Automatic or Manual (Automatic dominates most inventory). CVT coming in a future release. Pick multiple — any match is included.

## `cylinders` (type: `array`):

Filter by cylinder count. 4 and 6 are the most common; 8 is moderate; 3, 10 and 12 are rare; 0 = electric vehicles. Pick multiple — any match is included.

## `colors` (type: `array`):

Filter by exterior color (e.g. `GRAY`, `BLACK`, `WHITE`, `SILVER`, `MAROON`). ⚠️ Case-sensitive UPPERCASE — must match Copart's spelling. Bonus capability — Copart's own website doesn't offer a color filter, but this Actor can filter by it. Pick multiple — any match is included.

## `saleDatePreset` (type: `string`):

Quick filter for upcoming auctions. Server time (UTC). If both this and the custom dates below are set — preset wins. Leave empty to include all dates.

## `saleDateFrom` (type: `string`):

Custom lower bound (inclusive). Format `YYYY-MM-DD`. Interpreted as UTC start-of-day. Ignored if `Sale date — quick window` is set.

## `saleDateTo` (type: `string`):

Custom upper bound (inclusive). Format `YYYY-MM-DD`. Interpreted as UTC end-of-day. Ignored if `Sale date — quick window` is set.

## `salePlatforms` (type: `array`):

Limit results to specific Copart sale platforms. Leave empty to include all platforms.

## `excludeSalePlatforms` (type: `array`):

Exclude lots from specific sale platforms. Typical use: exclude Purple Wave (PWUSA) which carries higher buyer fees. Cannot overlap with `Sale platforms — include only`.

## `excludeOnApproval` (type: `boolean`):

Skip lots that require seller approval after sale (`On Approval` status). These often don't sell at first auction. Equivalent to Copart UI's 'Pure Sale Items' Featured filter.

## `currentBidMin` (type: `integer`):

Lowest current bid to include (inclusive, USD). ⚠️ Applied after fetching from Copart — Copart's search has no price filter. When set, the Actor fetches up to 3× more pages to leave room for filtering, which can raise per-run cost. You're still only charged for lots within your price range.

## `currentBidMax` (type: `integer`):

Highest current bid to include (inclusive, USD). Same fetch caveat as 'Current bid — min'. Pre-bid lots (no current bid yet) count as $0 — kept under this max, but dropped if you also set a positive 'Current bid — min'.

## `buyItNowOnly` (type: `boolean`):

Only show lots with a Buy It Now price (a small share of inventory). No extra fetch cost.

## `features` (type: `array`):

Mirrors Copart's UI 'Featured items' sidebar. Pick multiple — any match is included. Some Featured items live in dedicated fields above (Buy It Now → 'Buy It Now only', Run and Drive → 'Runs and Drives only', Electric/Hybrid → 'Fuel type', Recovered Thefts / Fleet & Lease → 'Source'). 'Pure Sale' here is the same as enabling 'Exclude On Approval lots'.

## `newlyAddedWithinDays` (type: `integer`):

Filter to lots added to Copart's inventory within the last N days. Distinct from 'Sale date — quick window' — this is when the lot APPEARED in inventory, not when its auction runs. Typical values: 1 (last 24h), 7 (last week), 30 (last month).

## `classicsYearsOld` (type: `integer`):

Override the 25-year default Classics threshold (only applies when `Featured items` includes 'Classics'). Useful for younger-classic ranges (e.g. 15 years) or stricter (e.g. 40 years).

## `vin` (type: `string`):

17-character Vehicle Identification Number (A-Z/0-9, excludes I/O/Q). Combines with other filters via AND — e.g. VIN + Makes=\[BMW] narrows to BMW lots matching this VIN. ⚠️ Only one of {VIN, Lot numbers, Free-form search} may be set per run.

## `lotNumbers` (type: `array`):

Look up a specific Copart lot by its lot number. Currently supports a single lot per run (multi-lot lookup coming later). ⚠️ Only one of {VIN, Lot numbers, Free-form search} may be set per run.

## `freeFormQuery` (type: `string`):

Full-text keyword search across all lot fields (description, make, model, etc.). Example: `low miles BMW`. Multi-token AND. Combines with other filters via AND. ⚠️ Only one of {VIN, Lot numbers, Free-form search} may be set per run.

## `webhookUrl` (type: `string`):

If set, each new/updated lot is POSTed to this URL as JSON (HMAC-signed if a secret is provided). Up to 3 attempts per delivery (initial + 2 retries, backoff 1s then 2s); failed deliveries are queued and retried at the start of the next run.

## `webhookSecret` (type: `string`):

Optional. When set, each webhook delivery includes an `X-CopartIntelligence-Signature` header = `sha256=<hex(hmac-sha256(secret, body))>`. Use this to verify deliveries originate from this Actor.

## `maxResultsPerRun` (type: `integer`):

Hard cap on the number of lots processed per Actor run. Protects against runaway charges on broad filters.

## `includeUpdated` (type: `boolean`):

When true, lots seen in a previous run whose details have changed are also output (charged as `lot_updated`, $0.02). When false, only brand-new lots are output (charged as `lot_new`, $0.05).

## `outputFormat` (type: `string`):

Verbosity of each Dataset row and webhook payload. `compact` (recommended) gives full buyer detail — odometer, primary/secondary damage, title, color, drivetrain, fuel, engine, cylinders, run condition, keys, yard name, buy-now price, and more — without the heavy per-panel damages array. `full` adds the per-panel `damages[]` array (with photo URLs), `thumbnailUrl`, `seller`, and the lot URL slug `ldu`. `minimal` keeps only the headline fields (lot, make/model/year, current bid, odometer, primary damage, title group, yard name, location state). The `_metadata` block is always present.

## `sortBy` (type: `string`):

Sort order, mirroring Copart's UI 'Sort by' dropdown. Leave empty for Copart's default (sale-light priority). Note: 'Location distance' (sort by nearest ZIP) is coming in a future release — it requires geographic coordinate resolution.

## Actor input object example

```json
{
  "makes": [
    "BMW"
  ],
  "models": [
    "X5"
  ],
  "yearMin": 2018,
  "runsAndDrivesOnly": false,
  "maxResultsPerRun": 500,
  "includeUpdated": true,
  "outputFormat": "compact"
}
```

# Actor output Schema

## `newAndUpdatedLots` (type: `string`):

Lots that are new (lot\_new event) or changed (lot\_updated event) since the previous run with the same filter input. Click to open the Dataset with all rows. Field-level descriptions live in dataset\_schema.json.

# 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 = {
    "makes": [
        "BMW"
    ],
    "models": [
        "X5"
    ],
    "yearMin": 2018
};

// Run the Actor and wait for it to finish
const run = await client.actor("gallant_illustration/auction-intelligence").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 = {
    "makes": ["BMW"],
    "models": ["X5"],
    "yearMin": 2018,
}

# Run the Actor and wait for it to finish
run = client.actor("gallant_illustration/auction-intelligence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "makes": [
    "BMW"
  ],
  "models": [
    "X5"
  ],
  "yearMin": 2018
}' |
apify call gallant_illustration/auction-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=gallant_illustration/auction-intelligence",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Copart Intelligence",
        "description": "Real-time Copart auction monitor. Filter by make, model, year, damage type, yard, sale date, fuel/drive/body, source (repos/theft recovery). New & updated lots streamed to your webhook or Apify Dataset. Pay-per-lot — $0.05 per new, $0.02 per update.",
        "version": "0.0",
        "x-build-id": "b4q8i20fnOAPeD0F3"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/gallant_illustration~auction-intelligence/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-gallant_illustration-auction-intelligence",
                "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/gallant_illustration~auction-intelligence/runs": {
            "post": {
                "operationId": "runs-sync-gallant_illustration-auction-intelligence",
                "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/gallant_illustration~auction-intelligence/run-sync": {
            "post": {
                "operationId": "run-sync-gallant_illustration-auction-intelligence",
                "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": {
                    "makes": {
                        "title": "Vehicle makes",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Pick from top 40 Copart brands by inventory OR type a custom make name (Lucid, VinFast, classic / specialty — anything not in the dropdown). Case-sensitive — verify exact spelling at the [Copart search page](https://www.copart.com/lotSearchResults). Note: some brands appear in both full + abbreviated forms (CHEV/CHEVROLET, NISS/NISSAN) — for full coverage of that brand, pick both. Pick multiple — any match is included.",
                        "items": {
                            "type": "string",
                            "enumSuggestedValues": [
                                "ACURA",
                                "ALFA ROMEO",
                                "AUDI",
                                "BMW",
                                "BMW MOTORRAD",
                                "BUICK",
                                "CADILLAC",
                                "CHEV",
                                "CHEVROLET",
                                "CHRYSLER",
                                "DODGE",
                                "FIAT",
                                "FORD",
                                "GENESIS",
                                "GMC",
                                "HONDA",
                                "HYUNDAI",
                                "INFINITI",
                                "JAGUAR",
                                "JEEP",
                                "KIA",
                                "LAND ROVER",
                                "LEXUS",
                                "LINCOLN",
                                "MASERATI",
                                "MAZDA",
                                "MERCEDES BENZ",
                                "MERCEDES-BENZ",
                                "MINI",
                                "MITSUBISHI",
                                "NISS",
                                "NISSAN",
                                "PORSCHE",
                                "RAM",
                                "RIVIAN",
                                "SUBARU",
                                "TESLA",
                                "TOYOTA",
                                "VOLKSWAGEN",
                                "VOLVO"
                            ],
                            "enumTitles": [
                                "Acura",
                                "Alfa Romeo",
                                "Audi",
                                "BMW",
                                "BMW Motorrad (motorcycles)",
                                "Buick",
                                "Cadillac",
                                "Chev (abbrev. Chevrolet)",
                                "Chevrolet",
                                "Chrysler",
                                "Dodge",
                                "Fiat",
                                "Ford",
                                "Genesis",
                                "GMC",
                                "Honda",
                                "Hyundai",
                                "Infiniti",
                                "Jaguar",
                                "Jeep",
                                "Kia",
                                "Land Rover",
                                "Lexus",
                                "Lincoln",
                                "Maserati",
                                "Mazda",
                                "Mercedes-Benz (no hyphen variant)",
                                "Mercedes-Benz",
                                "Mini",
                                "Mitsubishi",
                                "Niss (abbrev. Nissan)",
                                "Nissan",
                                "Porsche",
                                "RAM",
                                "Rivian",
                                "Subaru",
                                "Tesla",
                                "Toyota",
                                "Volkswagen",
                                "Volvo"
                            ]
                        }
                    },
                    "models": {
                        "title": "Models",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Vehicle models, e.g. X5, CAMRY, F-150. Case-sensitive. Best combined with `Makes` to avoid cross-make collisions (e.g. \"1500\" exists for both Chevrolet and RAM). Verify spelling at the [Copart search page](https://www.copart.com/lotSearchResults) — click 'Model' filter.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "yearMin": {
                        "title": "Year (from)",
                        "minimum": 1900,
                        "maximum": 2030,
                        "type": "integer",
                        "description": "Inclusive lower bound on the lot year. Leave empty for no lower bound."
                    },
                    "yearMax": {
                        "title": "Year (to)",
                        "minimum": 1900,
                        "maximum": 2030,
                        "type": "integer",
                        "description": "Inclusive upper bound on the lot year. Leave empty for no upper bound."
                    },
                    "odometerMax": {
                        "title": "Max odometer",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Upper bound on miles. Leave empty for no upper bound."
                    },
                    "vehicleTypes": {
                        "title": "Vehicle types",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Filter by vehicle type. Pick multiple — any match is included.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "automobile",
                                "atv",
                                "bus",
                                "motorcycle",
                                "dirt_bike",
                                "industrial_equipment",
                                "farm_equipment",
                                "jet_ski",
                                "medium_duty_truck",
                                "trailer",
                                "boat",
                                "construction_equipment",
                                "rv",
                                "snowmobile",
                                "heavy_duty_truck"
                            ],
                            "enumTitles": [
                                "Automobiles",
                                "ATVs",
                                "Buses",
                                "Motorcycles",
                                "Dirt Bikes",
                                "Industrial Equipment",
                                "Agriculture and Farm equipment",
                                "Jet Skis",
                                "Medium Duty / Box Trucks",
                                "Trailers",
                                "Boats",
                                "Construction equipment",
                                "RVs",
                                "Snowmobiles",
                                "Heavy Duty Trucks"
                            ]
                        }
                    },
                    "titleGroups": {
                        "title": "Title groups",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Filter by title group. Pick multiple — any match is included.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "clean",
                                "salvage",
                                "nonrepairable"
                            ],
                            "enumTitles": [
                                "Clean Title",
                                "Salvage",
                                "Nonrepairable"
                            ]
                        }
                    },
                    "damageCodes": {
                        "title": "Primary damage",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Filter by primary damage. Pick multiple — any match is included. All 25 damage categories Copart offers are supported.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "all_over",
                                "biohazard",
                                "burn",
                                "burn_engine",
                                "burn_interior",
                                "damage_history",
                                "frame_damage",
                                "front_end",
                                "hail",
                                "mechanical",
                                "minor_dent",
                                "altered_vin",
                                "normal_wear",
                                "partial_repair",
                                "rear_end",
                                "rejected_repair",
                                "replaced_vin",
                                "rollover",
                                "side",
                                "stripped",
                                "top_roof",
                                "undercarriage",
                                "unknown",
                                "vandalism",
                                "water_flood"
                            ],
                            "enumTitles": [
                                "All Over (multi-area, often total loss)",
                                "Biohazard / Chemical",
                                "Burn",
                                "Burn — Engine",
                                "Burn — Interior",
                                "Damage History (prior repair noted)",
                                "Frame Damage (structural)",
                                "Front End",
                                "Hail",
                                "Mechanical",
                                "Minor Dent / Scratches",
                                "Missing / Altered VIN",
                                "Normal Wear (no notable damage)",
                                "Partial Repair (incomplete fix)",
                                "Rear End",
                                "Rejected Repair (insurance refused fix)",
                                "Replaced VIN",
                                "Rollover",
                                "Side",
                                "Stripped (parts removed, theft recovery)",
                                "Top / Roof",
                                "Undercarriage",
                                "Unknown",
                                "Vandalism",
                                "Water / Flood"
                            ]
                        }
                    },
                    "location": {
                        "title": "Location (states + yards)",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Pick US states / Canadian provinces (entire state — auto-expands to every Copart yard there) and/or specific yards. Mix freely — any match is included (union). Example: pick \"Texas — all yards\" plus \"CA - Vallejo\" to monitor all of Texas plus that one California yard. Leave empty to search all locations. Note: the Washington DC yard is grouped under Maryland (MD) — picking \"Maryland — all yards\" includes it.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "AB",
                                "AK",
                                "AL",
                                "AR",
                                "AZ",
                                "CA",
                                "CO",
                                "CT",
                                "DE",
                                "FL",
                                "GA",
                                "HI",
                                "IA",
                                "ID",
                                "IL",
                                "IN",
                                "KS",
                                "KY",
                                "LA",
                                "MA",
                                "MD",
                                "ME",
                                "MI",
                                "MN",
                                "MO",
                                "MS",
                                "MT",
                                "NB",
                                "NC",
                                "ND",
                                "NE",
                                "NH",
                                "NJ",
                                "NM",
                                "NS",
                                "NV",
                                "NY",
                                "OH",
                                "OK",
                                "ON",
                                "OR",
                                "PA",
                                "QC",
                                "RI",
                                "SC",
                                "SD",
                                "TN",
                                "TX",
                                "UT",
                                "VA",
                                "VT",
                                "WA",
                                "WI",
                                "WV",
                                "WY",
                                "ab_calgary",
                                "ab_edmonton",
                                "ak_anchorage",
                                "al_birmingham",
                                "al_cusseta",
                                "al_dothan",
                                "al_mobile",
                                "al_mobile_south",
                                "al_montgomery",
                                "al_tanner",
                                "ar_fayetteville",
                                "ar_little_rock",
                                "az_phoenix",
                                "az_phoenix_north",
                                "az_tucson",
                                "ca_adelanto",
                                "ca_antelope",
                                "ca_bakersfield",
                                "ca_fresno",
                                "ca_hayward",
                                "ca_long_beach",
                                "ca_los_angeles",
                                "ca_martinez",
                                "ca_mentone",
                                "ca_napa",
                                "ca_rancho_cucamonga",
                                "ca_redding",
                                "ca_sacramento",
                                "ca_san_bernardino",
                                "ca_san_diego",
                                "ca_san_jose",
                                "ca_so_sacramento",
                                "ca_sun_valley",
                                "ca_vallejo",
                                "ca_van_nuys",
                                "co_colorado_springs",
                                "co_denver",
                                "co_denver_central",
                                "co_denver_south",
                                "ct_hartford",
                                "ct_hartford_springfield",
                                "de_seaford",
                                "fl_clewiston",
                                "fl_ft_pierce",
                                "fl_jacksonville_north",
                                "fl_miami_central",
                                "fl_miami_north",
                                "fl_miami_south",
                                "fl_ocala",
                                "fl_orlando_north",
                                "fl_orlando_south",
                                "fl_punta_gorda",
                                "fl_tallahassee",
                                "fl_tampa_north",
                                "fl_tampa_south",
                                "fl_west_palm_beach",
                                "ga_atlanta_east",
                                "ga_atlanta_north",
                                "ga_atlanta_south",
                                "ga_atlanta_west",
                                "ga_augusta",
                                "ga_cartersville",
                                "ga_fairburn",
                                "ga_macon",
                                "ga_savannah",
                                "ga_tifton",
                                "hi_honolulu",
                                "ia_cedar_rapids",
                                "ia_davenport",
                                "ia_des_moines",
                                "id_boise",
                                "il_chicago_north",
                                "il_chicago_south",
                                "il_peoria",
                                "il_southern_illinois",
                                "il_wheeling",
                                "in_cicero",
                                "in_dyer",
                                "in_fort_wayne",
                                "in_indianapolis",
                                "ks_kansas_city",
                                "ks_wichita",
                                "ky_earlington",
                                "ky_lexington_east",
                                "ky_lexington_west",
                                "ky_louisville",
                                "ky_walton",
                                "la_baton_rouge",
                                "la_new_orleans",
                                "la_shreveport",
                                "la_vinton",
                                "ma_freetown",
                                "ma_north_boston",
                                "ma_south_boston",
                                "ma_west_warren",
                                "dc_washington_dc",
                                "md_baltimore",
                                "md_baltimore_east",
                                "md_laurel",
                                "me_lyman",
                                "me_windham",
                                "mi_detroit",
                                "mi_flint",
                                "mi_ionia",
                                "mi_kincheloe",
                                "mi_lansing",
                                "mi_wayland",
                                "mn_minneapolis",
                                "mn_minneapolis_north",
                                "mn_st_cloud",
                                "mo_columbia",
                                "mo_sikeston",
                                "mo_springfield",
                                "mo_st_louis",
                                "ms_grenada",
                                "ms_jackson",
                                "mt_billings",
                                "mt_helena",
                                "nb_moncton",
                                "nc_china_grove",
                                "nc_concord",
                                "nc_gastonia",
                                "nc_lagrange",
                                "nc_lumberton",
                                "nc_mebane",
                                "nc_mocksville",
                                "nc_raleigh",
                                "nc_raleigh_north",
                                "nd_bismarck",
                                "ne_lincoln",
                                "nh_candia",
                                "nj_glassboro_east",
                                "nj_glassboro_west",
                                "nj_somerville",
                                "nj_trenton",
                                "nm_albuquerque",
                                "ns_halifax",
                                "nv_57_storage",
                                "nv_las_vegas",
                                "nv_las_vegas_west",
                                "nv_reno",
                                "ny_albany",
                                "ny_buffalo",
                                "ny_long_island",
                                "ny_newburgh",
                                "ny_rochester",
                                "ny_syracuse",
                                "oh_akron",
                                "oh_cleveland_east",
                                "oh_cleveland_west",
                                "oh_columbus",
                                "oh_dayton",
                                "ok_oklahoma_city",
                                "ok_tulsa",
                                "on_cookstown",
                                "on_london",
                                "on_ottawa",
                                "on_toronto",
                                "or_eugene",
                                "or_portland_north",
                                "or_portland_south",
                                "pa_altoona",
                                "pa_chambersburg",
                                "pa_harrisburg",
                                "pa_philadelphia",
                                "pa_philadelphia_east",
                                "pa_pittsburgh_north",
                                "pa_pittsburgh_south",
                                "pa_pittsburgh_west",
                                "pa_scranton",
                                "pa_york_haven",
                                "qc_montreal",
                                "ri_exeter",
                                "sc_columbia",
                                "sc_north_charleston",
                                "sc_spartanburg",
                                "sd_rapid_city",
                                "tn_knoxville",
                                "tn_memphis",
                                "tn_nashville",
                                "crashedtoys_dallas",
                                "tx_abilene",
                                "tx_amarillo",
                                "tx_andrews",
                                "tx_austin",
                                "tx_corpus_christi",
                                "tx_dallas",
                                "tx_dallas_south",
                                "tx_el_paso",
                                "tx_ft_worth",
                                "tx_houston",
                                "tx_houston_east",
                                "tx_longview",
                                "tx_lufkin",
                                "tx_mcallen",
                                "tx_north_austin",
                                "tx_san_antonio",
                                "tx_waco",
                                "ut_ogden",
                                "ut_salt_lake_city",
                                "va_danville",
                                "va_fredericksburg",
                                "va_hampton",
                                "va_richmond",
                                "va_richmond_east",
                                "vt_rutland",
                                "wa_north_seattle",
                                "wa_pasco",
                                "wa_spanaway",
                                "wa_spokane",
                                "wi_appleton",
                                "wi_madison_south",
                                "wi_milwaukee_north",
                                "wi_milwaukee_south",
                                "wv_charleston",
                                "wy_casper"
                            ],
                            "enumTitles": [
                                "Alberta — all yards",
                                "Alaska — all yards",
                                "Alabama — all yards",
                                "Arkansas — all yards",
                                "Arizona — all yards",
                                "California — all yards",
                                "Colorado — all yards",
                                "Connecticut — all yards",
                                "Delaware — all yards",
                                "Florida — all yards",
                                "Georgia — all yards",
                                "Hawaii — all yards",
                                "Iowa — all yards",
                                "Idaho — all yards",
                                "Illinois — all yards",
                                "Indiana — all yards",
                                "Kansas — all yards",
                                "Kentucky — all yards",
                                "Louisiana — all yards",
                                "Massachusetts — all yards",
                                "Maryland — all yards",
                                "Maine — all yards",
                                "Michigan — all yards",
                                "Minnesota — all yards",
                                "Missouri — all yards",
                                "Mississippi — all yards",
                                "Montana — all yards",
                                "New Brunswick — all yards",
                                "North Carolina — all yards",
                                "North Dakota — all yards",
                                "Nebraska — all yards",
                                "New Hampshire — all yards",
                                "New Jersey — all yards",
                                "New Mexico — all yards",
                                "Nova Scotia — all yards",
                                "Nevada — all yards",
                                "New York — all yards",
                                "Ohio — all yards",
                                "Oklahoma — all yards",
                                "Ontario — all yards",
                                "Oregon — all yards",
                                "Pennsylvania — all yards",
                                "Quebec — all yards",
                                "Rhode Island — all yards",
                                "South Carolina — all yards",
                                "South Dakota — all yards",
                                "Tennessee — all yards",
                                "Texas — all yards",
                                "Utah — all yards",
                                "Virginia — all yards",
                                "Vermont — all yards",
                                "Washington — all yards",
                                "Wisconsin — all yards",
                                "West Virginia — all yards",
                                "Wyoming — all yards",
                                "AB - Calgary",
                                "AB - Edmonton",
                                "AK - Anchorage",
                                "AL - Birmingham",
                                "AL - Cusseta",
                                "AL - Dothan",
                                "AL - Mobile",
                                "AL - Mobile South",
                                "AL - Montgomery",
                                "AL - Tanner",
                                "AR - Fayetteville",
                                "AR - Little Rock",
                                "AZ - Phoenix",
                                "AZ - Phoenix North",
                                "AZ - Tucson",
                                "CA - Adelanto",
                                "CA - Antelope",
                                "CA - Bakersfield",
                                "CA - Fresno",
                                "CA - Hayward",
                                "CA - Long Beach",
                                "CA - Los Angeles",
                                "CA - Martinez",
                                "CA - Mentone",
                                "CA - Napa",
                                "CA - Rancho Cucamonga",
                                "CA - Redding",
                                "CA - Sacramento",
                                "CA - San Bernardino",
                                "CA - San Diego",
                                "CA - San Jose",
                                "CA - So Sacramento",
                                "CA - Sun Valley",
                                "CA - Vallejo",
                                "CA - Van Nuys",
                                "CO - Colorado Springs",
                                "CO - Denver",
                                "CO - Denver Central",
                                "CO - Denver South",
                                "CT - Hartford",
                                "CT - Hartford Springfield",
                                "DE - Seaford",
                                "FL - Clewiston",
                                "FL - Ft. Pierce",
                                "FL - Jacksonville North",
                                "FL - Miami Central",
                                "FL - Miami North",
                                "FL - Miami South",
                                "FL - Ocala",
                                "FL - Orlando North",
                                "FL - Orlando South",
                                "FL - Punta Gorda",
                                "FL - Tallahassee",
                                "FL - Tampa North",
                                "FL - Tampa South",
                                "FL - West Palm Beach",
                                "GA - Atlanta East",
                                "GA - Atlanta North",
                                "GA - Atlanta South",
                                "GA - Atlanta West",
                                "GA - Augusta",
                                "GA - Cartersville",
                                "GA - Fairburn",
                                "GA - Macon",
                                "GA - Savannah",
                                "GA - Tifton",
                                "HI - Honolulu",
                                "IA - Cedar Rapids",
                                "IA - Davenport",
                                "IA - Des Moines",
                                "ID - Boise",
                                "IL - Chicago North",
                                "IL - Chicago South",
                                "IL - Peoria",
                                "IL - Southern Illinois",
                                "IL - Wheeling",
                                "IN - Cicero",
                                "IN - Dyer",
                                "IN - Fort Wayne",
                                "IN - Indianapolis",
                                "KS - Kansas City",
                                "KS - Wichita",
                                "KY - Earlington",
                                "KY - Lexington East",
                                "KY - Lexington West",
                                "KY - Louisville",
                                "KY - Walton",
                                "LA - Baton Rouge",
                                "LA - New Orleans",
                                "LA - Shreveport",
                                "LA - Vinton",
                                "MA - Freetown",
                                "MA - North Boston",
                                "MA - South Boston",
                                "MA - West Warren",
                                "DC - Washington DC",
                                "MD - Baltimore",
                                "MD - Baltimore East",
                                "MD - Laurel",
                                "ME - Lyman",
                                "ME - Windham",
                                "MI - Detroit",
                                "MI - Flint",
                                "MI - Ionia",
                                "MI - Kincheloe",
                                "MI - Lansing",
                                "MI - Wayland",
                                "MN - Minneapolis",
                                "MN - Minneapolis North",
                                "MN - St. Cloud",
                                "MO - Columbia",
                                "MO - Sikeston",
                                "MO - Springfield",
                                "MO - St. Louis",
                                "MS - Grenada",
                                "MS - Jackson",
                                "MT - Billings",
                                "MT - Helena",
                                "NB - Moncton",
                                "NC - China Grove",
                                "NC - Concord",
                                "NC - Gastonia",
                                "NC - Lagrange",
                                "NC - Lumberton",
                                "NC - Mebane",
                                "NC - Mocksville",
                                "NC - Raleigh",
                                "NC - Raleigh North",
                                "ND - Bismarck",
                                "NE - Lincoln",
                                "NH - Candia",
                                "NJ - Glassboro East",
                                "NJ - Glassboro West",
                                "NJ - Somerville",
                                "NJ - Trenton",
                                "NM - Albuquerque",
                                "NS - Halifax",
                                "NV - 57 Storage",
                                "NV - Las Vegas",
                                "NV - Las Vegas West",
                                "NV - Reno",
                                "NY - Albany",
                                "NY - Buffalo",
                                "NY - Long Island",
                                "NY - Newburgh",
                                "NY - Rochester",
                                "NY - Syracuse",
                                "OH - Akron",
                                "OH - Cleveland East",
                                "OH - Cleveland West",
                                "OH - Columbus",
                                "OH - Dayton",
                                "OK - Oklahoma City",
                                "OK - Tulsa",
                                "ON - Cookstown",
                                "ON - London",
                                "ON - Ottawa",
                                "ON - Toronto",
                                "OR - Eugene",
                                "OR - Portland North",
                                "OR - Portland South",
                                "PA - Altoona",
                                "PA - Chambersburg",
                                "PA - Harrisburg",
                                "PA - Philadelphia",
                                "PA - Philadelphia East",
                                "PA - Pittsburgh North",
                                "PA - Pittsburgh South",
                                "PA - Pittsburgh West",
                                "PA - Scranton",
                                "PA - York Haven",
                                "QC - Montreal",
                                "RI - Exeter",
                                "SC - Columbia",
                                "SC - North Charleston",
                                "SC - Spartanburg",
                                "SD - Rapid City",
                                "TN - Knoxville",
                                "TN - Memphis",
                                "TN - Nashville",
                                "CrashedToys Dallas",
                                "TX - Abilene",
                                "TX - Amarillo",
                                "TX - Andrews",
                                "TX - Austin",
                                "TX - Corpus Christi",
                                "TX - Dallas",
                                "TX - Dallas South",
                                "TX - El Paso",
                                "TX - Ft. Worth",
                                "TX - Houston",
                                "TX - Houston East",
                                "TX - Longview",
                                "TX - Lufkin",
                                "TX - McAllen",
                                "TX - North Austin",
                                "TX - San Antonio",
                                "TX - Waco",
                                "UT - Ogden",
                                "UT - Salt Lake City",
                                "VA - Danville",
                                "VA - Fredericksburg",
                                "VA - Hampton",
                                "VA - Richmond",
                                "VA - Richmond East",
                                "VT - Rutland",
                                "WA - North Seattle",
                                "WA - Pasco",
                                "WA - Spanaway",
                                "WA - Spokane",
                                "WI - Appleton",
                                "WI - Madison South",
                                "WI - Milwaukee North",
                                "WI - Milwaukee South",
                                "WV - Charleston",
                                "WY - Casper"
                            ]
                        }
                    },
                    "sources": {
                        "title": "Source",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Why the vehicle ended up at Copart. Pick multiple — any match is included. Repos and theft recovery often = clean cars with minimal damage; donations / impounds vary widely.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "donated",
                                "fleet_lease",
                                "impound",
                                "repossession",
                                "theft_recovery",
                                "water_flood"
                            ],
                            "enumTitles": [
                                "Donated",
                                "Fleet / Lease",
                                "Impound",
                                "Repossession",
                                "Theft Recovery",
                                "Water / Flood"
                            ]
                        }
                    },
                    "fuelTypes": {
                        "title": "Fuel type",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Filter by powertrain. EV / hybrid / diesel each have distinct resale dynamics. Pick multiple — any match is included. Note: Copart stores several hybrid spellings as separate values — to catch every hybrid, pick all three Hybrid options; likewise pick both Flexible options for full E85 coverage.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "gasoline",
                                "diesel",
                                "electric",
                                "electric_and_gas_hybrid",
                                "hybrid_engine",
                                "hybrid",
                                "flexible_fuel",
                                "flexible",
                                "compressed_natural_gas",
                                "hydrogen_fuel_cell",
                                "unknown"
                            ],
                            "enumTitles": [
                                "Gasoline",
                                "Diesel",
                                "Electric (EV)",
                                "Hybrid (Electric + Gas)",
                                "Hybrid (engine variant)",
                                "Hybrid (legacy)",
                                "Flexible Fuel (E85)",
                                "Flexible",
                                "Compressed Natural Gas (CNG)",
                                "Hydrogen Fuel Cell",
                                "Unknown"
                            ]
                        }
                    },
                    "driveTrains": {
                        "title": "Drive train",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Drive train. Each option covers Copart's different spellings for that drive type (e.g. FWD matches every front-wheel-drive spelling). Pick multiple — any match is included.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "4x2",
                                "awd",
                                "fwd",
                                "rwd",
                                "4x4_front",
                                "4x4_rear",
                                "unknown"
                            ],
                            "enumTitles": [
                                "Two-wheel drive (4×2 truck)",
                                "All-wheel drive (AWD)",
                                "Front-wheel drive (FWD)",
                                "Rear-wheel drive (RWD)",
                                "4×4 (FWD-based)",
                                "4×4 (RWD-based)",
                                "Unknown"
                            ]
                        }
                    },
                    "bodyStyles": {
                        "title": "Body style",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Body style. Each option covers Copart's many spelling variants for that style. Pick multiple — any match is included.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "sedan",
                                "suv",
                                "pickup",
                                "hatchback",
                                "coupe",
                                "convertible",
                                "wagon",
                                "cargo_van",
                                "passenger_van",
                                "minivan",
                                "cab_chassis",
                                "cutaway"
                            ],
                            "enumTitles": [
                                "Sedan",
                                "SUV",
                                "Pickup truck",
                                "Hatchback",
                                "Coupe",
                                "Convertible",
                                "Wagon",
                                "Cargo Van",
                                "Passenger Van",
                                "Minivan",
                                "Cab & Chassis",
                                "Cutaway"
                            ]
                        }
                    },
                    "runsAndDrivesOnly": {
                        "title": "Runs and Drives only",
                        "type": "boolean",
                        "description": "If true, only lots marked 'Run and Drive' are included.",
                        "default": false
                    },
                    "engines": {
                        "title": "Engine",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Filter by engine description. Free-text; multi-word OK (e.g. `2.0L 4`, `3.0L 6`, `4.4L 8`, `5.0L 12` — one space before the cylinder count). ⚠️ Case- and space-sensitive — copy the string verbatim from Copart's Engine facet (a spelling/spacing mismatch silently matches nothing). Copart has thousands of distinct engine descriptions. Pick multiple — any match is included.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "transmissions": {
                        "title": "Transmission",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Filter by transmission type — Automatic or Manual (Automatic dominates most inventory). CVT coming in a future release. Pick multiple — any match is included.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "AUTOMATIC",
                                "MANUAL"
                            ],
                            "enumTitles": [
                                "Automatic",
                                "Manual"
                            ]
                        }
                    },
                    "cylinders": {
                        "title": "Cylinders",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Filter by cylinder count. 4 and 6 are the most common; 8 is moderate; 3, 10 and 12 are rare; 0 = electric vehicles. Pick multiple — any match is included.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "0",
                                "3",
                                "4",
                                "6",
                                "8",
                                "10",
                                "12"
                            ],
                            "enumTitles": [
                                "0 (EV — no cylinders)",
                                "3",
                                "4",
                                "6",
                                "8",
                                "10",
                                "12"
                            ]
                        }
                    },
                    "colors": {
                        "title": "Exterior color",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Filter by exterior color (e.g. `GRAY`, `BLACK`, `WHITE`, `SILVER`, `MAROON`). ⚠️ Case-sensitive UPPERCASE — must match Copart's spelling. Bonus capability — Copart's own website doesn't offer a color filter, but this Actor can filter by it. Pick multiple — any match is included.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "saleDatePreset": {
                        "title": "Sale date — quick window",
                        "enum": [
                            "today",
                            "tomorrow",
                            "next_7_days",
                            "next_30_days"
                        ],
                        "type": "string",
                        "description": "Quick filter for upcoming auctions. Server time (UTC). If both this and the custom dates below are set — preset wins. Leave empty to include all dates."
                    },
                    "saleDateFrom": {
                        "title": "Sale date — custom from",
                        "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$",
                        "type": "string",
                        "description": "Custom lower bound (inclusive). Format `YYYY-MM-DD`. Interpreted as UTC start-of-day. Ignored if `Sale date — quick window` is set."
                    },
                    "saleDateTo": {
                        "title": "Sale date — custom to",
                        "pattern": "^(\\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$",
                        "type": "string",
                        "description": "Custom upper bound (inclusive). Format `YYYY-MM-DD`. Interpreted as UTC end-of-day. Ignored if `Sale date — quick window` is set."
                    },
                    "salePlatforms": {
                        "title": "Sale platforms — include only",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Limit results to specific Copart sale platforms. Leave empty to include all platforms.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "CPRTUSA",
                                "PWUSA",
                                "NCS"
                            ],
                            "enumTitles": [
                                "Copart USA (CPRTUSA)",
                                "Purple Wave (PWUSA)",
                                "National Crime/Salvage (NCS)"
                            ]
                        }
                    },
                    "excludeSalePlatforms": {
                        "title": "Sale platforms — exclude",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Exclude lots from specific sale platforms. Typical use: exclude Purple Wave (PWUSA) which carries higher buyer fees. Cannot overlap with `Sale platforms — include only`.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "CPRTUSA",
                                "PWUSA",
                                "NCS"
                            ],
                            "enumTitles": [
                                "Exclude Copart USA",
                                "Exclude Purple Wave (higher fees)",
                                "Exclude NCS"
                            ]
                        }
                    },
                    "excludeOnApproval": {
                        "title": "Exclude On Approval lots",
                        "type": "boolean",
                        "description": "Skip lots that require seller approval after sale (`On Approval` status). These often don't sell at first auction. Equivalent to Copart UI's 'Pure Sale Items' Featured filter."
                    },
                    "currentBidMin": {
                        "title": "Current bid — min ($)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Lowest current bid to include (inclusive, USD). ⚠️ Applied after fetching from Copart — Copart's search has no price filter. When set, the Actor fetches up to 3× more pages to leave room for filtering, which can raise per-run cost. You're still only charged for lots within your price range."
                    },
                    "currentBidMax": {
                        "title": "Current bid — max ($)",
                        "minimum": 0,
                        "type": "integer",
                        "description": "Highest current bid to include (inclusive, USD). Same fetch caveat as 'Current bid — min'. Pre-bid lots (no current bid yet) count as $0 — kept under this max, but dropped if you also set a positive 'Current bid — min'."
                    },
                    "buyItNowOnly": {
                        "title": "Buy It Now only",
                        "type": "boolean",
                        "description": "Only show lots with a Buy It Now price (a small share of inventory). No extra fetch cost."
                    },
                    "features": {
                        "title": "Featured items",
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Mirrors Copart's UI 'Featured items' sidebar. Pick multiple — any match is included. Some Featured items live in dedicated fields above (Buy It Now → 'Buy It Now only', Run and Drive → 'Runs and Drives only', Electric/Hybrid → 'Fuel type', Recovered Thefts / Fleet & Lease → 'Source'). 'Pure Sale' here is the same as enabling 'Exclude On Approval lots'.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "used",
                                "no_license_required",
                                "hot_items",
                                "featured_vehicles",
                                "offsite_sales",
                                "engine_start",
                                "enhanced",
                                "classics",
                                "inspected",
                                "public_and_general_business",
                                "bank_repossessed",
                                "pure_sale"
                            ],
                            "enumTitles": [
                                "Used Vehicles",
                                "No License Required",
                                "Hot Items",
                                "Featured Vehicles",
                                "Offsite Sales",
                                "Engine Start Program",
                                "Enhanced Vehicles",
                                "Classics (25+ years)",
                                "Inspected",
                                "Public / General Business",
                                "Bank / Repossessed",
                                "Pure Sale (no approval)"
                            ]
                        }
                    },
                    "newlyAddedWithinDays": {
                        "title": "Newly added within last N days",
                        "minimum": 1,
                        "maximum": 30,
                        "type": "integer",
                        "description": "Filter to lots added to Copart's inventory within the last N days. Distinct from 'Sale date — quick window' — this is when the lot APPEARED in inventory, not when its auction runs. Typical values: 1 (last 24h), 7 (last week), 30 (last month)."
                    },
                    "classicsYearsOld": {
                        "title": "Classics — years-old threshold",
                        "minimum": 1,
                        "maximum": 100,
                        "type": "integer",
                        "description": "Override the 25-year default Classics threshold (only applies when `Featured items` includes 'Classics'). Useful for younger-classic ranges (e.g. 15 years) or stricter (e.g. 40 years)."
                    },
                    "vin": {
                        "title": "VIN search",
                        "pattern": "^[A-HJ-NPR-Z0-9]{17}$",
                        "type": "string",
                        "description": "17-character Vehicle Identification Number (A-Z/0-9, excludes I/O/Q). Combines with other filters via AND — e.g. VIN + Makes=[BMW] narrows to BMW lots matching this VIN. ⚠️ Only one of {VIN, Lot numbers, Free-form search} may be set per run."
                    },
                    "lotNumbers": {
                        "title": "Lot numbers",
                        "maxItems": 1,
                        "uniqueItems": true,
                        "type": "array",
                        "description": "Look up a specific Copart lot by its lot number. Currently supports a single lot per run (multi-lot lookup coming later). ⚠️ Only one of {VIN, Lot numbers, Free-form search} may be set per run.",
                        "items": {
                            "type": "string",
                            "pattern": "^\\d+$"
                        }
                    },
                    "freeFormQuery": {
                        "title": "Free-form search",
                        "type": "string",
                        "description": "Full-text keyword search across all lot fields (description, make, model, etc.). Example: `low miles BMW`. Multi-token AND. Combines with other filters via AND. ⚠️ Only one of {VIN, Lot numbers, Free-form search} may be set per run."
                    },
                    "webhookUrl": {
                        "title": "Webhook URL",
                        "type": "string",
                        "description": "If set, each new/updated lot is POSTed to this URL as JSON (HMAC-signed if a secret is provided). Up to 3 attempts per delivery (initial + 2 retries, backoff 1s then 2s); failed deliveries are queued and retried at the start of the next run."
                    },
                    "webhookSecret": {
                        "title": "Webhook HMAC secret",
                        "type": "string",
                        "description": "Optional. When set, each webhook delivery includes an `X-CopartIntelligence-Signature` header = `sha256=<hex(hmac-sha256(secret, body))>`. Use this to verify deliveries originate from this Actor."
                    },
                    "maxResultsPerRun": {
                        "title": "Max results per run",
                        "minimum": 1,
                        "maximum": 10000,
                        "type": "integer",
                        "description": "Hard cap on the number of lots processed per Actor run. Protects against runaway charges on broad filters.",
                        "default": 500
                    },
                    "includeUpdated": {
                        "title": "Include updated lots (not just new)",
                        "type": "boolean",
                        "description": "When true, lots seen in a previous run whose details have changed are also output (charged as `lot_updated`, $0.02). When false, only brand-new lots are output (charged as `lot_new`, $0.05).",
                        "default": true
                    },
                    "outputFormat": {
                        "title": "Output format",
                        "enum": [
                            "compact",
                            "full",
                            "minimal"
                        ],
                        "type": "string",
                        "description": "Verbosity of each Dataset row and webhook payload. `compact` (recommended) gives full buyer detail — odometer, primary/secondary damage, title, color, drivetrain, fuel, engine, cylinders, run condition, keys, yard name, buy-now price, and more — without the heavy per-panel damages array. `full` adds the per-panel `damages[]` array (with photo URLs), `thumbnailUrl`, `seller`, and the lot URL slug `ldu`. `minimal` keeps only the headline fields (lot, make/model/year, current bid, odometer, primary damage, title group, yard name, location state). The `_metadata` block is always present.",
                        "default": "compact"
                    },
                    "sortBy": {
                        "title": "Sort results by",
                        "enum": [
                            "auction_date",
                            "odometer",
                            "year",
                            "make",
                            "model",
                            "item_number",
                            "buy_it_now",
                            "current_bid",
                            "sale_light"
                        ],
                        "type": "string",
                        "description": "Sort order, mirroring Copart's UI 'Sort by' dropdown. Leave empty for Copart's default (sale-light priority). Note: 'Location distance' (sort by nearest ZIP) is coming in a future release — it requires geographic coordinate resolution."
                    }
                }
            },
            "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
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```