{
  "openapi": "3.0.1",
  "info": {
    "title": "Used Car Scraper for CarGurus - Listings, VINs & Dealer Leads",
    "description": "Scrape used-car listings & dealer leads from CarGurus by ZIP or search URL: VIN, price, Instant Market Value & deal rating, mileage, specs, photos, plus dealer name, phone & address. Independent tool - not affiliated with or endorsed by CarGurus, Inc.; all trademarks belong to their owners.",
    "version": "0.1",
    "x-build-id": "zqvbQHT0v6mKlyhWJ"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapesage~cargurus-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapesage-cargurus-scraper",
        "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/scrapesage~cargurus-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapesage-cargurus-scraper",
        "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/scrapesage~cargurus-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapesage-cargurus-scraper",
        "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": {
          "zipCodes": {
            "title": "ZIP codes",
            "type": "array",
            "description": "5-digit US ZIP codes to search around. Each ZIP is its own search of used cars within the search radius; the run checks that CarGurus applied the ZIP, and a ZIP CarGurus does not know is named on the run card and nothing is billed for it. One per row (e.g. 90001, 78704).",
            "items": {
              "type": "string"
            }
          },
          "searchUrls": {
            "title": "CarGurus search URLs",
            "type": "array",
            "description": "Paste CarGurus search-results links (build a search on cargurus.com with your filters and copy the address). Links to cargurus.com/search with a ZIP run exactly as they are. A make or model page (cargurus.com/Cars/l-Used-Honda-Civic-d586) has no place of its own, so add &zip=12345 to it or put a ZIP in zipCodes; city pages (..._L34369) keep their city. One per row.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs (search or listing detail)",
            "type": "array",
            "description": "CarGurus links to scrape directly: search-results links (as in CarGurus search URLs) or single listings (https://www.cargurus.com/details/<id>), which come back as full listing rows with details. Auto-detected. One per row.",
            "items": {
              "type": "string"
            }
          },
          "distance": {
            "title": "Search radius (miles)",
            "minimum": 10,
            "maximum": 500,
            "type": "integer",
            "description": "Radius around each ZIP code to search, in miles. Cars farther away that a dealer offers to ship are left out unless you turn on includeDeliveryListings.",
            "default": 50
          },
          "sortBy": {
            "title": "Sort by",
            "enum": [
              "best_match",
              "newest_listed",
              "lowest_price",
              "highest_price",
              "lowest_mileage",
              "best_deal",
              "closest_first",
              "newest_car_year"
            ],
            "type": "string",
            "description": "Order of the results, applied by CarGurus. With Best match, CarGurus mixes a few paid listings into each page (each row's placement field names them); with any other order those paid slots are left out, so the rows keep the order you chose.",
            "default": "best_match"
          },
          "maxResults": {
            "title": "Max results (listings)",
            "minimum": 1,
            "maximum": 100000,
            "type": "integer",
            "description": "Cap on car-listing records across the whole run, shared fairly between your searches. Searches page automatically until this cap or the page limit is reached. (Dealer-lead records do not count against this cap.)",
            "default": 100
          },
          "maxPagesPerSearch": {
            "title": "Max pages per search",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "How many result pages (about 22 listings each) to read per ZIP or search URL before moving on.",
            "default": 10
          },
          "includeListingDetails": {
            "title": "Include full listing details",
            "type": "boolean",
            "description": "Read each listing's detail record for the richest row: the seller's description, the full options list, vehicle history (accidents, owners, title, fleet use), price history, all photos, safety features and NHTSA crash ratings, legroom and cargo space, the trim's original MSRP and dealer fees, plus the dealer's own website, rating and map position. One extra request per listing, billed only when the details arrive.",
            "default": false
          },
          "includeDealerLeads": {
            "title": "Also output dealer leads",
            "type": "boolean",
            "description": "Output one deduplicated dealer record (type `dealer`) per dealership seen: name, phone, full street address, city/state/ZIP and logo, plus the dealer's own website, rating and map position when listing details are on.",
            "default": false
          },
          "conditionFilter": {
            "title": "Condition",
            "enum": [
              "any",
              "used",
              "cpo",
              "new"
            ],
            "type": "string",
            "description": "Keep only listings of a given condition (applied by CarGurus and checked on every row). CarGurus' used-car search has no new cars, so \"New\" finds nothing.",
            "default": "any"
          },
          "dealRatingFilter": {
            "title": "Deal rating filter",
            "type": "array",
            "description": "Keep only listings with one of these CarGurus deal ratings (applied by CarGurus). Leave empty for all.",
            "items": {
              "type": "string",
              "enum": [
                "GREAT_PRICE",
                "GOOD_PRICE",
                "FAIR_PRICE",
                "POOR_PRICE",
                "OVERPRICED"
              ],
              "enumTitles": [
                "Great Price",
                "Good Price",
                "Fair Price",
                "High Price",
                "Overpriced"
              ]
            },
            "default": []
          },
          "makeFilter": {
            "title": "Make filter",
            "type": "array",
            "description": "Keep only these makes, as CarGurus names them (case-insensitive: Toyota, Ford, Mercedes-Benz, Land Rover; Chevy, VW and Mercedes work too). CarGurus applies them to each ZIP search; a make CarGurus does not have is named on the run card. Leave empty for all.",
            "items": {
              "type": "string"
            }
          },
          "minYear": {
            "title": "Minimum year",
            "minimum": 0,
            "maximum": 2100,
            "type": "integer",
            "description": "Keep only listings from this model year or newer. 0 = no filter.",
            "default": 0
          },
          "maxYear": {
            "title": "Maximum year",
            "minimum": 0,
            "maximum": 2100,
            "type": "integer",
            "description": "Keep only listings from this model year or older. 0 = no filter.",
            "default": 0
          },
          "maxMileage": {
            "title": "Maximum mileage",
            "minimum": 0,
            "maximum": 1000000,
            "type": "integer",
            "description": "Keep only listings at or below this mileage. 0 = no filter.",
            "default": 0
          },
          "minPrice": {
            "title": "Minimum price (USD)",
            "minimum": 0,
            "maximum": 100000000,
            "type": "integer",
            "description": "Keep only listings whose listed price (before dealer fees) is at or above this. 0 = no filter.",
            "default": 0
          },
          "maxPrice": {
            "title": "Maximum price (USD)",
            "minimum": 0,
            "maximum": 100000000,
            "type": "integer",
            "description": "Keep only listings whose listed price (before dealer fees) is at or below this. 0 = no filter.",
            "default": 0
          },
          "withDealerPhoneOnly": {
            "title": "Only listings with a dealer phone",
            "type": "boolean",
            "description": "Output only listings that have a dealer phone number (best for lead generation).",
            "default": false
          },
          "excludePrivateSellers": {
            "title": "Exclude private sellers",
            "type": "boolean",
            "description": "Output only dealer listings, skipping private (for-sale-by-owner) sellers.",
            "default": false
          },
          "deduplicateListings": {
            "title": "Deduplicate listings",
            "type": "boolean",
            "description": "Skip a listing already delivered by another search in the same run (overlapping ZIP areas). Within one search a listing is never repeated.",
            "default": true
          },
          "includeDeliveryListings": {
            "title": "Include cars dealers can ship from farther away",
            "type": "boolean",
            "description": "CarGurus can add cars from dealers outside your radius that offer delivery. Off: only cars within the search radius. On: CarGurus' own mix, which can include cars hundreds of miles away (each row's distance field shows it).",
            "default": false
          },
          "monitorMode": {
            "title": "Monitoring mode - only new & price-changed listings",
            "type": "boolean",
            "description": "Remember listings (and their last price) from previous runs and emit ONLY new listings and price-changed ones (each tagged monitorStatus = new / price_drop / price_increase). The first run also records the rest of each search (up to Max pages per search) without billing it, so later runs report only cars that are really new. Pairs with Apify Schedules.",
            "default": false
          },
          "monitorStoreName": {
            "title": "Monitor store name",
            "type": "string",
            "description": "Named key-value store that holds the 'already seen' listing ids + prices for monitoring mode. Use a different name per tracked target/search to keep their histories separate.",
            "default": "cargurus-scraper-monitor"
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum parallel detail requests (up to 4 are used at a time). Lower it if you see transient blocks.",
            "default": 8
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. The default (Apify proxy, automatic) uses datacenter IPs and switches the run to US residential IPs by itself if CarGurus refuses datacenter. Custom settings are used as given.",
            "default": {
              "useApifyProxy": true
            }
          },
          "urlsFromFile": {
            "title": "Import URLs from a file",
            "type": "string",
            "description": "Paste a list of CarGurus URLs (one per line), OR one link to a .txt/.csv file, Google Sheet or Google Drive file containing them. Lets you import many search or listing URLs at once instead of typing each. Google Sheet/Drive share links are handled automatically."
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}