# Cars Vehicle Search (`agentx/cars-vehicle-search`) Actor Search public Cars.com vehicle inventory in the United States by keyword and optional ZIP radius. Export normalized prices, vehicle details, images, dealer context, and source URLs. - **URL**: https://apify.com/agentx/cars-vehicle-search.md - **Developed by:** [AgentX](https://apify.com/agentx) (community) - **Categories:** E-commerce, Lead generation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $4.13 / 1,000 results 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/platform/actors/running/actors-in-store#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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 **Cars Vehicle Search is a United States Cars.com listings API for keyword and optional ZIP-radius research, returning source-linked vehicle records in one normalized 35-field Dataset.** - **United States-focused input:** the public country cannot route to an unrelated international market. - **Automatic Cars.com source lock:** every focused run is restricted to the named marketplace. - **Optional ZIP-area search:** a resolved US ZIP applies a 50-mile Cars.com distance. - **35 documented fields:** absent source values remain empty instead of becoming inferred vehicle facts. [**Run a one-result test**](https://apify.com/agentx/cars-vehicle-search) ยท [**View the API page**](https://apify.com/agentx/cars-vehicle-search/api) For the smallest controlled test, use `Toyota Camry` near `10001`, set `max_results` to `1`, and budget at most $0.01900 on the FREE tier for one published item plus Actor Start. The runtime is source-locked to Cars.com; the public Store and API pages were not live during the July 21, 2026 audit and remain a publication gate. ### Why Choose This API #### Cars.com inventory with automatic source control Cars Vehicle Search accepts a vehicle keyword and publishes normalized records from public Cars.com inventory. A qualifying result can include price, currency, make, model, trim, year, mileage, body type, fuel, drivetrain, condition, exterior color, VIN, seller or location context, images, listing ID, and a direct Cars.com URL when the source exposes those values. The public schema is intentionally focused on the United States and does not expose a platform selector. The runtime resolves this Actor to Cars.com before country and location checks, so an input payload cannot broaden a run to another United States marketplace. Use All Vehicle Scraper when multi-source comparison is intentional. #### Source-linked, nullable data Every item uses a common vehicle schema, but no source is required to populate every field. Missing values remain empty. `source_url` provides the review path for inventory, price, mileage, seller, and vehicle-detail checks. Cars Vehicle Search is not affiliated with Cars.com. It is not an inspection, title-history service, ownership database, valuation guarantee, financing offer, or dealer-contact enrichment product. Listings can be updated or removed after collection. ### Quick Start Guide #### How to run a controlled search 1. Open [Cars Vehicle Search](https://apify.com/agentx/cars-vehicle-search). 2. Keep `country` set to `United States` and enter `Toyota Camry`. 3. Optionally enter a city or ZIP such as `10001`. 4. Set `max_results` to `1`, start the Actor, and confirm `platform` is `Cars.com` before increasing volume. Use the same scenario in the Console and integrations: ```json { "country": "United States", "keyword": "Toyota Camry", "location": "10001", "max_results": 1 } ```` The keyword is trimmed but not translated, expanded, or replaced. A supplied location must resolve to a US postal code for the Cars.com geographic filter. Omit `location` for a countrywide search. `max_results` is a ceiling, not guaranteed inventory. ### Input Parameters #### Configuration fields | Parameter | Type | Required | Accepted value and behavior | | --- | --- | --- | --- | | `country` | string | Yes | `United States`, the only public country for this focused Actor. | | `keyword` | string | Yes | A non-empty make, model, trim, or vehicle phrase. | | `location` | string | No | US city or ZIP. A resolved ZIP applies a 50-mile Cars.com search distance. | | `max_results` | integer | Yes | 1 to 10,000; maximum records returned by the source-locked Cars.com run. | Country, keyword, and max results are required; location remains optional. Source selection is deliberately absent because the focused runtime enforces Cars.com and ignores any attempt to override the source. #### Location behavior Use a five-digit ZIP for the most deterministic geographic input. If a city resolves to a postal code, the normalized ZIP is used. If it does not resolve, the Actor rejects the source for that location rather than labeling countrywide results as local. ### Output Data Schema #### Complete normalized record Each result uses 33 vehicle fields plus `processor` and `processed_at`, for 35 fields total. | Field group | Fields | | --- | --- | | Identity | `title`, `listing_id`, `vin`, `description` | | Images | `main_image`, `images` | | Price | `price`, `currency`, `price_text` | | Vehicle | `year`, `make`, `model`, `trim`, `condition`, `body_type`, `fuel`, `transmission`, `engine`, `drive_type`, `exterior_color`, `interior_color` | | Mileage | `mileage`, `mileage_unit` | | Seller and market | `seller`, `seller_type`, `location`, `country`, `platform` | | Links and dates | `source_url`, `platform_url`, `official_url`, `posted_at`, `updated_at` | | Processing | `processor`, `processed_at` | This abbreviated example shows the contract without representing a current live listing: ```json { "main_image": "https://example.com/cars/toyota-camry.jpg", "title": "Used 2021 Toyota Camry XLE", "price": 24500, "currency": "USD", "year": 2021, "make": "Toyota", "model": "Camry", "trim": "XLE", "mileage": 58200, "mileage_unit": "mi", "condition": "used", "location": "New York, NY", "country": "United States", "platform": "Cars.com", "source_url": "https://www.cars.com/vehicledetail/example/", "listing_id": "example", "processor": "https://apify.com/username/actor_name", "processed_at": "2026-07-21T12:00:00Z" } ``` The default Dataset overview exposes all 35 fields. Current export formats are documented by the [Dataset items API](https://docs.apify.com/api/v2/dataset-items-get) and include JSON, JSONL, CSV, Excel, XML, HTML, and RSS. ### Integration Examples #### REST API The intended owner/name identifier is `agentx/cars-vehicle-search`. The public Store API returned no current Actor record for this identifier on July 21, 2026, so this README does not invent a numeric Actor ID or reuse old online statistics. After publication, run the controlled scenario synchronously: ```bash curl -L "https://api.apify.com/v2/actors/agentx~cars-vehicle-search/run-sync-get-dataset-items?maxItems=1" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -H "Authorization: Bearer " \ -d '{ "country": "United States", "keyword": "Toyota Camry", "location": "10001", "max_results": 1 }' ``` The official [synchronous Actor endpoint](https://docs.apify.com/api/v2/act-run-sync-get-dataset-items-post) documents current authentication, timeout, response, and charge-limit options. #### MCP Apify currently documents a hosted Streamable HTTP MCP server: ```json { "mcpServers": { "apify": { "url": "https://mcp.apify.com?tools=actors,docs" } } } ``` After the Actor is published, ask the MCP client to find `agentx/cars-vehicle-search`, inspect its schema, run the one-result Toyota Camry scenario, and retrieve the Dataset item. Cars.com is selected automatically. Running Actors requires authentication. See the [Apify MCP guide](https://docs.apify.com/integrations/mcp). #### Scheduled and workflow runs Apify schedules, webhooks, Make, n8n, and client SDKs can consume the same input and Dataset after publication. Scheduled inputs use the same four-field contract and remain source-locked to Cars.com. Verify Actor identity in the live integration picker rather than pasting an unverified numeric ID. ### Pricing & Cost Calculator Cars Vehicle Search uses pay-per-event pricing. Actor Start is charged when a run begins, and one `result` event is charged for every item written to the default Dataset. | Billed event and tier | Price per event | Billing unit | | --- | ---: | --- | | Actor Start | $0.01000 | One Actor run start. | | Result - FREE | $0.00900 | One published Dataset item. | | Result - BRONZE | $0.00870 | One published Dataset item. | | Result - SILVER | $0.00840 | One published Dataset item. | | Result - GOLD | $0.00810 | One published Dataset item. | | Result - PLATINUM | $0.00810 | One published Dataset item. | | Result - DIAMOND | $0.00810 | One published Dataset item. | On the FREE tier, the smallest one-result test costs $0.01000 + $0.00900 = **$0.01900**. A run that publishes no item can still incur Actor Start. Each Cars.com record written to the default Dataset creates one `result` event. Confirm live pricing on the Store after publication. ### Use Cases & Applications #### Inventory and pricing research Collect repeated Cars.com samples for a make, model, or trim and compare asking price, year, mileage, condition, and location. Use source URLs to review outliers before placing them in a report. #### Dealer and market monitoring Track public inventory changes for a ZIP area, create review queues for newly observed listings, or export seller and location context when present. This is research data, not permission to contact or profile a seller. #### Data pipelines and AI-assisted analysis Load normalized records into spreadsheets, databases, dashboards, search indexes, or internal analysis workflows. Keep nullable fields nullable and retain `source_url` as provenance. AI-generated conclusions should not override the source page or an independent vehicle inspection. #### When to choose another option Use the multi-platform All Vehicle Scraper when cross-market comparison is intentional. Browse Cars.com manually for a one-off purchase decision requiring full page context. Use an authorized dedicated feed when contractual completeness or every native field is required. ### FAQ #### Which inputs are required? `country`, `keyword`, and `max_results` are required. `location` is optional; no platform selector is exposed. #### Can I select another United States marketplace? No. This focused Actor is locked to Cars.com. Use All Vehicle Scraper when another marketplace or multi-source comparison is intended. #### How does location work? A resolved US ZIP is sent with a 50-mile distance. Omit location for a countrywide keyword search. #### Why are some fields empty? Cars.com search results do not expose every normalized field for every listing. The Actor does not invent missing values. #### Does `max_results` guarantee that count? No. It is a ceiling. Live inventory, source availability, unique listing IDs, and publishable records determine the result count. #### Can records become outdated? Yes. Listings, prices, and availability can change after collection. Rerun for current data and treat older items as historical. #### Can I schedule the Actor? Yes, after publication. Scheduled runs remain source-locked without a platform field. #### How is billing counted? Each Dataset item triggers one result event; Actor Start is billed separately. ### Trust & Data Quality - **Traceable records:** direct Cars.com source URLs support manual verification. - **Stable public contract:** 35 Dataset fields align with the current normalized output schema. - **Transparent optionality:** absent source values remain empty. - **Conservative proof:** old online data, ratings, user counts, and unverified Actor IDs are not treated as current evidence. - **Source-lock regression gate:** a record attributed to any platform other than Cars.com is treated as a defect. For a reproducible issue, provide the run ID, exact input, expected platform, and one public source URL. Do not include API tokens, private data, or dealer credentials. ### Legal & Compliance Cars Vehicle Search is intended for lawful analysis of publicly accessible vehicle listing information. Users are responsible for applicable laws, source terms, privacy rules, intellectual-property rights, data retention, and contractual restrictions. Do not use output for unlawful profiling, discrimination, fraud, unauthorized resale, or access to non-public information. Vehicle information should be independently verified before purchase, financing, insurance, safety, or valuation decisions. This Actor does not certify a vehicle or seller. ### Related Tools #### Vehicle research - [All Vehicle Scraper](https://apify.com/agentx/all-vehicle-scraper) supports intentional multi-country and multi-source research. - [AutoTrader Vehicle Search](https://apify.com/agentx/autotrader-vehicle-search) is source-locked to Autotrader US. - [Auto Trader UK Vehicle Search](https://apify.com/agentx/auto-trader-uk-vehicle-search) focuses on UK inventory and requires a postal location at runtime. #### Enrichment and workflow tools - [Google Maps Store Scraper](https://apify.com/agentx/google-maps-store-scraper) supports separate public business research. - [All Shopping Scraper](https://apify.com/agentx/all-shopping-scraper) supports product and retail comparisons. - [All Jobs Scraper](https://apify.com/agentx/all-jobs-scraper) supports multi-platform job listing workflows. These project relationships were verified locally; each Store link must be rechecked after publication. ### Support & Community - **Store:** [Cars Vehicle Search](https://apify.com/agentx/cars-vehicle-search) - **API:** [Cars Vehicle Search API](https://apify.com/agentx/cars-vehicle-search/api) - **Official source:** [Cars.com Toyota Camry listings](https://www.cars.com/shopping/toyota-camry/) - **Platform help:** [Apify documentation](https://docs.apify.com/) - **Community:** [Apify Actor Telegram](https://t.me/Apify_Actor) - **Direct support:** [AiAgentApi support](https://t.me/AiAgentApi) Verified against local schemas, pricing metadata, source-lock regression evidence, and the current public Cars.com surface on **July 21, 2026**. Local Cars.com-only routing now passes; unresolved Store/API links remain a publication gate. [**Run a one-result Cars.com test**](https://apify.com/agentx/cars-vehicle-search) ยท [**Review the API page**](https://apify.com/agentx/cars-vehicle-search/api) # Actor input Schema ## `country` (type: `string`): United States is the only public market for this focused Actor. ## `keyword` (type: `string`): Required vehicle make, model, or search phrase sent without translation or replacement. ## `location` (type: `string`): Optional US city or ZIP code. A resolved ZIP applies a 50-mile Cars.com search distance. ## `max_results` (type: `integer`): Maximum Cars.com records returned. This is a ceiling, not guaranteed inventory. ## Actor input object example ```json { "country": "United States", "keyword": "Toyota Camry", "max_results": 50 } ``` # Actor output Schema ## `results` (type: `string`): Open the overview table for normalized vehicle listings from the selected supported platforms. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "country": "United States", "keyword": "Toyota Camry", "max_results": 50 }; // Run the Actor and wait for it to finish const run = await client.actor("agentx/cars-vehicle-search").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "country": "United States", "keyword": "Toyota Camry", "max_results": 50, } # Run the Actor and wait for it to finish run = client.actor("agentx/cars-vehicle-search").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 '{ "country": "United States", "keyword": "Toyota Camry", "max_results": 50 }' | apify call agentx/cars-vehicle-search --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=agentx/cars-vehicle-search", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Cars Vehicle Search", "description": "Search public Cars.com vehicle inventory in the United States by keyword and optional ZIP radius. Export normalized prices, vehicle details, images, dealer context, and source URLs.", "version": "1.0", "x-build-id": "aqnjdhWfXhx4ihJQ3" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/agentx~cars-vehicle-search/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-agentx-cars-vehicle-search", "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/agentx~cars-vehicle-search/runs": { "post": { "operationId": "runs-sync-agentx-cars-vehicle-search", "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/agentx~cars-vehicle-search/run-sync": { "post": { "operationId": "run-sync-agentx-cars-vehicle-search", "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", "required": [ "country", "keyword", "max_results" ], "properties": { "country": { "title": "๐ŸŒ Country", "enum": [ "United States" ], "type": "string", "description": "United States is the only public market for this focused Actor." }, "keyword": { "title": "๐Ÿ” Keyword", "type": "string", "description": "Required vehicle make, model, or search phrase sent without translation or replacement." }, "location": { "title": "๐Ÿ“ Location", "type": "string", "description": "Optional US city or ZIP code. A resolved ZIP applies a 50-mile Cars.com search distance." }, "max_results": { "title": "๐Ÿ“Š Max Results", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum Cars.com records returned. This is a ceiling, not guaranteed inventory." } } }, "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 } } } } } } } } } } ```