# Cars For Sale Scraper (`muhammadafzal/cars-for-sale-scraper`) Actor

Extract public CarsForSale.com vehicle listings with price, mileage, VIN, specifications, dealer details, location, images, features, and source URLs.

- **URL**: https://apify.com/muhammadafzal/cars-for-sale-scraper.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** Automation, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 vehicle records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Cars For Sale Scraper

> **Free-plan limit:** Apify free-plan runs can return at most **5 dataset records per run** from this Actor, even if you request more.

Extract public vehicle listings from CarsForSale.com into structured JSON, CSV, Excel, or API-ready dataset records. The Actor accepts CarsForSale.com search/result pages and individual vehicle-detail URLs.

### What you get

Each delivered vehicle can include:

- listing URL and listing ID
- title, year, make, model, and trim
- price, currency, mileage, VIN, and stock number
- body type, fuel type, transmission, engine, and drivetrain
- exterior/interior color, description, features, and image URLs
- dealer name, dealer phone, location, source URL, and scrape timestamp

Fields unavailable on a public page are returned as `null` or an empty array, never invented.

### Input

```json
{
  "startUrls": [{ "url": "https://www.carsforsale.com/toyota-for-sale-C648118" }],
  "maxResults": 25,
  "maxPages": 3,
  "includeDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "US"
  }
}
```

Use `includeDetails: false` when URLs alone are sufficient. It is faster but detail fields will be `null`. `maxResults` is enforced across all input URLs and limits delivered/billed records.

For production traffic that CarsForSale.com has allowlisted, set the optional Apify secret `CARS_FOR_SALE_PROXY_URL` to a DataImpulse HTTP proxy URL. This encrypted secret takes precedence over the input `proxyConfiguration` fallback. Port 823 is a rotating gateway; the Actor adds a fresh per-run `sessid` targeting suffix automatically so the browser's IP, cookies, and fingerprint stay coherent. Existing DataImpulse targeting/session parameters are preserved. The secret is read only at runtime and is never written to logs or output.

### Output example

```json
{
  "url": "https://www.carsforsale.com/vehicle/details/ABC123",
  "listingId": "ABC123",
  "title": "2022 Toyota Camry XSE",
  "year": 2022,
  "make": "Toyota",
  "model": "Camry",
  "trim": "XSE",
  "price": 28995,
  "currency": "USD",
  "mileage": 32100,
  "vin": "4T1G11AK1NU123456",
  "dealerName": "Example Motors",
  "imageUrls": ["https://cdn.example/car.jpg"],
  "sourceUrl": "https://www.carsforsale.com/search?zipcode=90210&radius=50",
  "scrapedAt": "2026-08-28T12:00:00.000Z"
}
```

The default dataset contains vehicles only. Run diagnostics are written to the `OUTPUT` key-value-store record with one of: `DATA`, `EMPTY`, `BLOCKED`, `REJECTED`, or `FAILED`. A target challenge is reported as `HTTP_403_CHALLENGE` with challenged URLs and an allowlisting next step; a proxy transport failure is reported separately as `PROXY_TUNNEL_FAILURE`.

### Pricing

This Actor uses **pay-per-event** pricing. These are the current Apify Store event prices:

| Event | Price (USD) | When it is charged |
|---|---:|---|
| `vehicle-result` | FREE: $0.025; BRONZE: $0.025; SILVER: $0.025; GOLD: $0.02; PLATINUM: $0.02; DIAMOND: $0.02 | Vehicle record — Charged once after a unique CarsForSale.com vehicle record is saved to the dataset. |
| `apify-actor-start` | $0.005 | Actor Start — Charged when the Actor starts running. Number of events charged depends on Actor memory (one event per GB, minimum one event). — Charged once per run. |

Apify platform usage for this Actor run is included alongside the event prices above; no separate per-run platform-usage fee is passed to users.

This covers Apify platform usage for this Actor run. Other Apify products or usage outside this Actor run may still follow your account plan.

### Reliability and responsible use

CarsForSale.com can present Cloudflare or CAPTCHA challenges. The Actor identifies itself as `CarsForSaleScraper/1.1`, uses coherent US residential browser sessions, bounded retries, low concurrency, and explicit blocker detection. CarsForSale.com asks blocked feed providers to contact its crawler team with their outbound IP ranges and User-Agent; operators running this Actor at scale should request allowlisting from CarsForSale.com. The `OUTPUT` record reports `blocker.type: HTTP_403_CHALLENGE` and the access path used. The Actor does not solve CAPTCHAs or bypass authentication. A fully challenged run returns `BLOCKED`, zero fabricated records, and zero vehicle-result charges. Valid partial records are preserved.

Scrape only public data you are permitted to collect. Follow the source website's terms, robots policies, applicable privacy laws, and restrictions on personal data. This Actor is not affiliated with CarsForSale.com.

### What data does Cars For Sale Scraper return?

| Field | Type | Description |
|---|---|---|
| `url` | string | Value returned as url. |
| `listingId` | string or null | Value returned as listingId. |
| `title` | string | Value returned as title. |
| `year` | integer or null | Value returned as year. |
| `make` | string or null | Value returned as make. |
| `model` | string or null | Value returned as model. |
| `trim` | string or null | Value returned as trim. |
| `price` | number or null | Value returned as price. |
| `currency` | string or null | Value returned as currency. |
| `mileage` | integer or null | Value returned as mileage. |
| `vin` | string or null | Value returned as vin. |
| `stockNumber` | string or null | Value returned as stockNumber. |
| `bodyType` | string or null | Value returned as bodyType. |
| `fuelType` | string or null | Value returned as fuelType. |
| `transmission` | string or null | Value returned as transmission. |
| `engine` | string or null | Value returned as engine. |
| `drivetrain` | string or null | Value returned as drivetrain. |
| `exteriorColor` | string or null | Value returned as exteriorColor. |
| `interiorColor` | string or null | Value returned as interiorColor. |
| `description` | string or null | Value returned as description. |
| `dealerName` | string or null | Value returned as dealerName. |
| `dealerPhone` | string or null | Value returned as dealerPhone. |
| `location` | string or null | Value returned as location. |
| `imageUrls` | array | Value returned as imageUrls. |

### Use cases

- Schedule repeatable collection and export results to downstream workflows.
- Monitor public products, prices, availability, sellers, and catalog changes.
- Run a one-off research job and export the structured result as JSON, CSV, Excel, XML, or RSS from Apify.
- Schedule the same input to monitor changes over time and send completed datasets to a webhook or integration.
- Feed schema-shaped records into a database, spreadsheet, BI tool, or AI workflow with the source URL retained for verification.

### Run Cars For Sale Scraper with the Apify API

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('muhammadafzal/cars-for-sale-scraper').call({
  "startUrls": [
    {
      "url": "https://www.carsforsale.com/toyota-for-sale-C648118"
    }
  ],
  "maxResults": 25,
  "maxPages": 3,
  "includeDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

You can also run the Actor from Apify Console, schedules, webhooks, the REST API, Make, Zapier, n8n, or the hosted Apify MCP server.

### Support

When reporting a problem, include the **Actor run ID**, a redacted input, the expected result, and a small public example URL when applicable. Do not post API tokens, cookies, credentials, or personal data in an issue.

# Actor input Schema

## `startUrls` (type: `array`):

Use CarsForSale.com search/result URLs or individual vehicle URLs. Only public carsforsale.com HTTPS URLs are accepted.

## `maxResults` (type: `integer`):

Stop after this many unique vehicle records. Range: 1–500; default: 25.

## `maxPages` (type: `integer`):

Follow at most this many result pages per run. Range: 1–20; default: 3. Ignored for direct vehicle URLs.

## `includeDetails` (type: `boolean`):

Open each vehicle page for VIN, mileage, dealer, specifications, description, and images. Disable for faster summary-only records.

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

Fallback proxy configuration. When the Actor owner has configured the encrypted CARS\_FOR\_SALE\_PROXY\_URL secret, that permitted DataImpulse proxy is used automatically and takes precedence over this field; otherwise this uses a US residential Apify session. Proxy credentials are never entered here or logged.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.carsforsale.com/toyota-for-sale-C648118"
    }
  ],
  "maxResults": 25,
  "maxPages": 3,
  "includeDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

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

Structured public CarsForSale.com vehicle records.

## `summary` (type: `string`):

Outcome, record/page/event counts, and warnings.

# 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 = {
    "startUrls": [
        {
            "url": "https://www.carsforsale.com/toyota-for-sale-C648118"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/cars-for-sale-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "startUrls": [{ "url": "https://www.carsforsale.com/toyota-for-sale-C648118" }] }

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/cars-for-sale-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://www.carsforsale.com/toyota-for-sale-C648118"
    }
  ]
}' |
apify call muhammadafzal/cars-for-sale-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/cars-for-sale-scraper"
        }
    }
}
```

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

## OpenAPI specification

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