Batch scoring
POST /v1/predict/batch scores several properties in one request and returns one answer per
property, in the order you submitted them. It is the call for the moment you have a list —
ten leads to triage before standup — and you want the numbers that decide which two are worth
a closer look.
A batch is one Metered Call and costs one Credit per property submitted, the same at every Tier. The member-by-member schema is in the API reference; this page is what the call is, what comes back, and — the part to read before you send one — exactly what it charges for.
⚠️ The answer carries the core numbers only
A batch entry is the answer a single Scored Call returns for that property, minus the list of comparable sales.
Everything you need to judge the deal is here: the valuation range, the Comp Band, the repair
budget and target margin the numbers were built on — yours when you sent them, this service's
own figures when you did not — the maximum allowable offer with its clamped flag, the
cost stack, and the subject_property block showing which house the numbers actually ran on.
The one thing that is not here is comps — the individual sales behind the band.
Where the comparable sales are. Score the property on its own with POST /v1/predict and
the full comps list comes back. Ask by address: a Scored Call identifies a property by
address only, and property_id is not one of the members it accepts. The property_id in the
batch entry's subject_property block is still worth keeping — it tells you which record the
batch scored, and it is the identifier the History Call takes when the recorded
transaction story is what you want.
Why it works this way. A batch of ten properties would otherwise return ten comp lists, a
payload written for nobody. The evidence that supports each number is still in the answer:
the Comp Band is the range the sales imply, effective_sample_size says how many qualified,
and as_is_similar_band is the price-per-square-foot range taken over them. The workflow the
endpoint is built for is triage on the batch, then look closely at the two that pencil —
and looking closely is a single call.
The vocabulary is the vocabulary
A batch entry names its members exactly as a single Scored Call names them — the headline
is max_allowable_offer, and every other member means what it means on
POST /v1/predict. There is one scoring vocabulary and one version of it, on every path
that returns a price; see the Versioning page.
If you are reading max_allowable_offer for the first time, reading a
score explains what the figure is — a ceiling, not a prediction — and
what clamped is telling you when it reads true.
The request
A properties array, each entry exactly the body POST /v1/predict accepts:
Code
The envelope accepts no other members. Duplicate addresses are allowed, and each one is charged — two identical entries are two work items.
The batch size limit is published in the API reference as maxItems on the
properties array, and it is the limit the API actually enforces.
What it costs, and when Credits come back
Two halves, and both matter:
- Charged per property submitted. A batch of ten costs ten Credits.
- Refunded per property that fails for a reason the refund policy covers — one Credit back per such property, as its own Refund on your Ledger.
The whole-batch rules
A batch is charged in full before any property is scored. The cost is known and paid up front, as a single Spend.
A batch that cannot be charged in full is rejected in full. If your Balance cannot cover every property in it, nothing is charged, nothing is split, and the request can be retried unchanged after a top-up. Batches are never partially accepted.
A batch over the documented limit is rejected before any Spend, with a 413 carrying
honest limit and submitted counts, so you can see exactly how far over you were.
The per-property rules
A property that fails for a covered reason does not stop the ones after it. Its entry carries the failure, its share of the Credits comes back as its own Refund, and every property after it is still attempted.
A failed property's entry is the same Problem Detail a single call would have returned for
it — the same type, the same wording. An integration branching on type needs no second
contract. The response is still 200; the entry itself says what happened.
The covered reasons are the same as for a single Scored Call, and there are five: the
address matched more than one property; the address is outside the covered area; the address
could not be scored; an upstream service could not complete the call; or an upstream service
did not answer in time. Each of the five is on the errors page with its own type,
and batch adds none of its own.
A refusal outside those five stops the batch. If a property fails in a way none of the
five covers, the batch stops there: the properties after it are not attempted, no results
array comes back, and the whole request answers
503 spend-indeterminate instead. Every Credit recorded for
the batch is returned to the Account as a Refund — including for the properties that had
already scored, whose answers are not returned — and the request is retryable.
You are charged for every property that produced an answer, and for nothing else.
Reading the response
Code
One entry per submitted property, in submission order, none omitted and none reordered.
Entry i answers submitted property i — the position is how you identify which property an
entry belongs to.
Telling the two apart: only an error entry carries status and type. A scored entry
carries neither.
The Trace ID rides the trace-id response header, not the body, and every entry in one
batch shares the one Trace ID of the call that produced it. Quote it if you contact support
at [email protected] about a batch.
Retries
Send an Idempotency-Key header to make a retry safe. Keys behave exactly as they do on
POST /v1/predict — see idempotency. Sending the same body to the
single endpoint and the batch endpoint under one key is a conflict, never a replay.