# Compact Excavator Auction Bid Ceiling (`boundedtools/compact-excavator-bid-ceiling`) Actor

Calculate a transparent buyer-specific maximum bid and walk-away price for one used compact-excavator auction lot.

- **URL**: https://apify.com/boundedtools/compact-excavator-bid-ceiling.md
- **Developed by:** [Sean](https://apify.com/boundedtools) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$13.50 / private valuation

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

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## Compact Excavator Auction Bid Ceiling

**Paste a compact-excavator auction lot. Add your transport, repair, fees, and target margin. Get the maximum price you can bid without destroying your economics.**

This Actor turns one used compact-excavator lot into a transparent bid ceiling. It shows the lot facts it could substantiate, the assumptions you supplied, every cost in the waterfall, three resale/bid scenarios, a recommended maximum bid, and the first bid increment at which you should walk away.

Run the free synthetic example first. It takes no source access and makes no billable event call.

### Who it is for

- Small equipment resellers and refurbishers
- Contractors buying used compact excavators
- Equipment-rental operators
- Active auction buyers who need a repeatable bid discipline

The Actor is intentionally narrow: **one used compact excavator per run**. It is not a general auction-valuation platform.

### What you get

One stable JSON decision packet in the default dataset and the `OUTPUT` key-value-store record:

- normalized lot facts and per-fact provenance;
- missing, uncertain, and conflicting facts;
- buyer-supplied assumptions separated from defaults;
- buyer-supplied or comparable-derived resale range;
- repair, transport, loading/removal, inspection, holding, financing, tax, fee, margin, and risk-reserve calculations;
- conservative, base, and aggressive bid ceilings;
- a confidence-selected maximum bid rounded down to your auction increment;
- the next bid increment as the hard walk-away price;
- one-way sensitivity for resale, repairs, transport, and required margin;
- input, source-content, and comparable-set hashes for reproducibility.

This is **buyer decision support**, not a certified appraisal, inspection, guaranteed profit, or certified market value.

### Five-minute free example

Use this input in Apify Console:

```json
{
  "mode": "free_example"
}
```

The fixed synthetic Kubota KX040-4 example produces:

| Result | USD |
|---|---:|
| Conservative ceiling | 16,475.29 |
| Base ceiling | 20,680.94 |
| Aggressive ceiling | 24,026.04 |
| Recommended maximum bid | **20,600.00** |
| Walk-away price | **20,700.00** |

The example's base resale value is $36,600. At the exact $20,680.94 base ceiling, the waterfall consumes the full resale value after a $5,490 required margin and $1,830 risk reserve. The operational recommendation rounds down to the configured $100 bid increment.

### Private valuation input

For `mode: "valuation"`, provide exactly one lot source:

1. `lotData`: canonical buyer-supplied JSON (most reliable);
2. `uploadedHtml`: buyer-exported/copied HTML, at most 2 MB; or
3. `lotUrl`: one permitted HTTPS page using the restrictive opt-in policy below.

Then provide your `buyer` economics and either `comparables`, `comparablesCsv`, or `resaleEstimate`.

```json
{
  "mode": "valuation",
  "sourceReference": "buyer-export://lot-8421",
  "lotData": {
    "assetType": "compact_excavator",
    "manufacturer": "Takeuchi",
    "model": "TB240",
    "year": 2020,
    "hours": 2350,
    "condition": "fair",
    "location": "Columbus, Ohio, US",
    "knownMissingFacts": ["serviceHistory", "undercarriageWearMeasurement"]
  },
  "buyer": {
    "currency": "USD",
    "auctionFee": {
      "fixed": 75,
      "tiers": [
        { "upTo": 10000, "percent": 12 },
        { "upTo": 30000, "percent": 8 },
        { "upTo": null, "percent": 5 }
      ]
    },
    "transportCost": 1450,
    "loadingRemovalCost": 250,
    "repairAllowance": { "low": 1800, "base": 4200, "high": 8500 },
    "inspectionCost": 450,
    "holdingMonths": 4,
    "monthlyHoldingCost": 225,
    "annualCapitalRatePercent": 14,
    "marginPercentOfResale": 16,
    "minimumMarginAmount": 3500,
    "riskBufferPercentOfResale": 7,
    "minimumRiskBufferAmount": 1800,
    "purchaseTaxPercent": 0,
    "taxAppliesToFees": false,
    "expectedResaleChannel": "dealer retail",
    "bidIncrement": 100
  },
  "resaleEstimate": {
    "low": 30000,
    "base": 35500,
    "high": 40500,
    "basis": "Buyer-owned transaction history for three recent TB240 units."
  }
}
```

Replace defaults with real costs. Any default used is listed in `defaultAssumptions.appliedFields` and important cost defaults produce warnings.

### Comparable interface

Comparable records are deliberately source-neutral so a licensed or permitted provider can be added later without changing the valuation engine.

```json
{
  "reference": "YOUR-COMP-001",
  "manufacturer": "Kubota",
  "model": "KX040-4",
  "year": 2019,
  "hours": 3000,
  "condition": "fair",
  "price": 32750,
  "priceType": "sold",
  "date": "2026-05-19",
  "source": "buyer archive"
}
```

The Actor applies fixed, versioned adjustments:

- asking prices: 0.92 realization factor;
- year: 1.5% per year, capped at ±20%;
- hours: 4% per 1,000-hour difference, capped at ±20%;
- explicit condition factors;
- higher weights for same-model, same-manufacturer, and sold-price records.

One or two comparables are accepted, but the range is widened and flagged. Zero comparable records require an explicit buyer resale range; the Actor will not invent one.

### Valuation waterfall

For each scenario, the maximum hammer bid is the greatest bid—resolved to one cent—that satisfies:

```text
resale value
- hammer bid
- auction fee (fixed, percentage, or progressive tiers)
- purchase tax
- transport
- loading/removal
- repair allowance
- inspection
- holding cost
- simple capital cost over the holding period
- required buyer margin
- uncertainty/risk reserve
>= 0
```

The conservative case uses low resale, high repairs, and 1.25× risk reserve. The base case uses base values. The aggressive case uses high resale, low repairs, and 0.75× risk reserve. “Aggressive” is not a recommendation to exceed your economics.

### URL and rights behavior

There is no built-in bypass and no auction site is silently enabled. For direct acquisition you must set all of:

```json
{
  "lotUrl": "https://permitted.example/lot/8421",
  "sourcePolicy": {
    "enabled": true,
    "rightsConfirmed": true,
    "allowedHosts": ["permitted.example"]
  }
}
```

The URL adapter:

- accepts one HTTPS page only;
- requires an exact hostname (no wildcards), standard TLS port, and buyer confirmation of permission;
- rejects credentials, literal IPs, local/private/reserved DNS results, unsafe redirects, non-HTML responses, and oversized bodies;
- checks `robots.txt` and fails closed if it cannot verify it;
- rechecks the exact host and robots rules after every redirect;
- never uses a proxy, authentication, cookies, CAPTCHA solving, or anti-bot bypass.

If a page is gated, disallowed, ambiguous, or unavailable, use buyer-exported HTML or structured lot JSON. Do not submit listing photos, full catalogs, or full copyrighted descriptions. Output retains derived facts, minimal evidence excerpts, hashes, and source references—not photos or a listing replica.

### API usage

Call the public Actor with the standard Apify API. This example runs the free synthetic valuation; replace the request body with a private valuation input like the one above when needed.

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/boundedtools~compact-excavator-bid-ceiling/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"mode":"free_example"}'
```

Retrieve the run's default dataset or `OUTPUT` record using the URLs exposed by the Actor output schema. Apify also generates API examples and integrations from the input/output schemas.

### Pricing

This Actor uses Apify pay per event.

- **Free synthetic example:** $0.00. `mode=free_example` does not trigger the paid `private-valuation` event.
- **Private valuation:** $13.50 per successful private valuation.
- **Failed or invalid private runs:** the `private-valuation` event is not charged.
- **Platform usage:** included. Users are not charged a separate platform-usage fee.

The paid event is attempted at most once per run and only after the valuation calculation succeeds. The result is saved and delivered immediately after a successful charge; if the run's charge limit does not permit the event, the private result is not delivered.

### Privacy and security

- Inputs and results stay in the caller's per-run Apify storage; no shared cross-customer dataset is created.
- Logs contain valuation ID, one-way lot fingerprint, event class, error code, and warning count—not buyer costs, raw HTML, account identity, or full listing text.
- The Actor does not request secrets, credentials, names, emails, cookies, or outcome data.
- Input/HTML/CSV/body sizes and comparable counts are capped.
- HTML is treated as text; scripts are removed and never executed.
- Hashes make repeated calculations auditable without redistributing source material.

### What it does not do

- It does not certify condition, title, ownership, emissions compliance, transport legality, or market value.
- It does not inspect photos or infer a precise undercarriage percentage.
- It does not access paid/restricted sold-price databases.
- It does not log in, solve CAPTCHA, evade bot controls, scrape catalogs in bulk, or fetch a URL unless the restrictive policy is explicitly enabled.
- It does not replace a physical inspection, tax advice, freight quote, or buyer judgment.

### Limitations

The first model is intentionally spreadsheet-auditable. Comparable quality dominates resale quality. Asking prices may not transact; sparse evidence widens the range but cannot remove market uncertainty. Repairs, removal, taxes, fees, and resale velocity are buyer-specific. Unknown condition is explicitly inferred and never presented as observed.

# Actor input Schema

## `mode` (type: `string`):

free\_example uses the complete synthetic example and is not billable. valuation processes your private lot and charges one valuation event after success.

## `lotUrl` (type: `string`):

One HTTPS lot page. The exact host must be allowlisted and rightsConfirmed must be true. Redirects, robots rules, DNS, content type, and size are checked.

## `uploadedHtml` (type: `string`):

HTML copied or exported by the buyer. Scripts are never executed. Maximum 2 MB. Do not submit full catalogs or content you may not process.

## `sourceReference` (type: `string`):

Optional URL, lot number, filename, or internal reference for HTML/structured inputs.

## `lotData` (type: `object`):

Canonical buyer-supplied lot facts. Do not guess missing values. Optional evidence entries are compared with the selected fact and conflicts are flagged.

## `buyer` (type: `object`):

All money values use the selected currency. Negative costs are rejected; zero costs are accepted and flagged where risky.

## `comparables` (type: `array`):

Up to 100 comparable records with reference, manufacturer, model, year, hours, condition, price, priceType (sold or asking), and optional date.

## `comparablesCsv` (type: `string`):

Alternative CSV with headers reference,manufacturer,model,year,hours,condition,price,priceType,date,source. Maximum 1 MB.

## `resaleEstimate` (type: `object`):

Optional object {low,base,high,basis}. Use when comparable records are unavailable. The output labels this as a buyer assumption.

## `sourcePolicy` (type: `object`):

Set enabled and rightsConfirmed true and list the exact allowed host. The adapter remains fail-closed.

## Actor input object example

```json
{
  "mode": "free_example",
  "lotData": {},
  "buyer": {},
  "comparables": [],
  "resaleEstimate": {},
  "sourcePolicy": {}
}
```

# Actor output Schema

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

No description

## `valuation` (type: `string`):

No description

# 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 = {
    "lotUrl": "",
    "uploadedHtml": "",
    "sourceReference": "",
    "comparablesCsv": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("boundedtools/compact-excavator-bid-ceiling").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 = {
    "lotUrl": "",
    "uploadedHtml": "",
    "sourceReference": "",
    "comparablesCsv": "",
}

# Run the Actor and wait for it to finish
run = client.actor("boundedtools/compact-excavator-bid-ceiling").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "lotUrl": "",
  "uploadedHtml": "",
  "sourceReference": "",
  "comparablesCsv": ""
}' |
apify call boundedtools/compact-excavator-bid-ceiling --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,boundedtools/compact-excavator-bid-ceiling"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/z51gI2I1gFeIFxvIz/builds/hb5rwae9WIHWdkrgb/openapi.json