The batch lookupendpoint
POST /v1_2/listings/vehicles/batch takes 1 to 100 vehicle ids in a JSON body and returns them in the order you sent them, with any id we cannot find coming back as null so the array still lines up with your input. It is priced one keyed charge per id: 1 millicredit each.
How do I look up many vehicle listings in one call?
POST /v1_2/listings/vehicles/batch with a JSON body carrying an ids array of 1 to 100 vehicle ids. The response uses the data plus meta envelope, where data is positionally aligned with what you sent and meta reports count. An id we cannot find is returned as null in its own slot rather than dropped, so position 7 of the response is always the answer to position 7 of your request. An empty list answers 400 batch_empty and more than 100 ids answers 400 batch_too_large. Pricing is per id, not per call: each id is one keyed charge of 1 millicredit, exactly what those lookups would have cost one at a time. What batching saves you is round trips and rate-limit headroom, not credits.
Ids only - VINs do not go in a batch
The ids array takes vehicle ids. A VIN names a car, and one car can be advertised by several dealers at once, which is why a VIN key on the single-vehicle route comes back with claim arrays attached. A batch slot has room for exactly one answer, so it keys on ids, which name exactly one listing each. Resolve VINs on the vehicles route first, keep the ids, and batch from there.
Positional alignment is the contract
data comes back in your input order with misses as null, so you can zip it straight against your request without matching on id. Do not strip the nulls before you align, and do not read a full-length array as proof that every id hit - meta.count reports the number of slots, not the number of matches.
Rows carry dealer identity, never claim groups
Each returned row is a sparse card carrying dealer_site_id, plus dealer_id where the website resolves to a dealership we hold a record for. What batch rows never carry is co_listings or other_claimants. Those answer the question of who else is advertising a given VIN, and a batch key is an id, which has already picked out one specific listing.
One keyed charge per id, and errors are refunded
A hundred ids in one call costs 100 millicredits, a tenth of a credit, the same as a hundred separate lookups would. What changes is that it is a single request against your 100-per-second rate limit instead of a hundred of them. Any 4xx or 5xx on the call is refunded in full, so a request rejected as batch_too_large costs nothing at all.
Frequently asked questions
How many vehicle listings can I look up in one batch?
Between 1 and 100 ids per call. An empty ids array answers 400 batch_empty and more than 100 answers 400 batch_too_large. The ceiling is published live as max_batch_ids at GET /v1_2/listings/meta, which is the value to read at runtime rather than hard-coding 100 into your client.
Does a batch lookup cost less than individual lookups?
No, and it does not claim to. Batch is priced one keyed charge per id, so 100 ids cost 100 millicredits - precisely what 100 single lookups would cost. What you save is latency and rate-limit budget: one request rather than a hundred against a key limited to 100 requests per second. The credit cost is identical either way.
What comes back for an id that does not exist?
A null in that position. The data array is positionally aligned with the ids you sent, so a miss holds its slot instead of shifting everything after it. The call itself still succeeds with a 200: an unknown id inside a batch is not an error, unlike on the single-vehicle route, where an unmatched key answers 404 vehicle_not_found.
Can I send VINs to the batch endpoint?
No. It takes vehicle ids. A VIN can be claimed by more than one dealer at the same time, and the batch contract gives each input exactly one slot, so VINs are handled on the single-vehicle route where those extra claims can be returned as co_listings and other_claimants. Look a VIN up there once, store the id it resolves to, then use batch to refresh it later.
More vehicle listings
Try Hermes Data for $0.99
Self-serve access to the automotive data your business runs on. The $0.99 trial gives you 20 credits to spend across Contacts, Dealers, and Dealer Groups. Then auto-upgrade to Starter ($99/mo) — or cancel any time.
Contacts, Dealers, and Dealer Groups are all self-serve on one credit wallet — spend your trial credits on any of them. Vehicle Listings is live too, on its own API subscription (separate from the credit wallet). Explore Listings.