Runs and polling

A run takes a minute or two: it gathers listings, scores them, and has a model read each finalist's words and photos. No request is held open that long. Starting one queues work and answers at once with where to read (Location) and how long to wait (Retry-After). You poll that same URL until status is terminal; when it is, the results are on the same response. There is no second "fetch results" endpoint. To be told when it ends instead of asking, name a callback URL: Get told when a run finishes.

Two paths: product or headless

If you triggered a search through the API and expected homes in the platform: you used the headless door. Run it through a search's runs, or walk the full journey. Headless is for a server that only wants homes back.

The contract (for a person or an AI)

1. Kick off. POST with an Idempotency-Key. Expect 202 (live market) or 201 (data set, already complete). Read Location and Retry-After from the response headers.
2. Poll. GET that Location (or the run or execution id you already have). Honor Retry-After between reads (2 seconds while unfinished). Do not poll faster — a run changes about once a second at most.
3. Stop when terminal. Product path: complete, failed, or canceled. Headless: succeeded, failed, or canceled. While unfinished, progress fields (step / stepLabel / progress, or the run's status) are for narration only.
4. Read the payload on the same GET. Product: results (homes, scores, reasons) are on the run once status is complete. Headless: result (with shortlist) is on the execution once status is succeeded. No extra call.

// Product path — same pattern works for an AI loop.
const headers = { Authorization: `Bearer ${process.env.LIVIA_API_KEY}` }
const started = await fetch(`https://liviamatch.com/api/v1/searches/${searchId}/runs`, {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': `run-${searchId}-1` },
})
const location = started.headers.get('Location')! // /api/v1/runs/{id}
const terminal = new Set(['complete', 'failed', 'canceled'])

let run
for (let attempt = 0; attempt < 150; attempt++) {
  const response = await fetch(`https://liviamatch.com${location}`, { headers })
  run = (await response.json()).data
  if (terminal.has(run.status)) break
  const wait = Number(response.headers.get('Retry-After') ?? 2)
  await new Promise((resolve) => setTimeout(resolve, wait * 1000))
}
if (run.status !== 'complete') throw new Error(`ended as ${run.status}`)
// The results are on this same payload.
for (const home of run.results) console.log(home.rank, home.address, home.score)

Status values

Product runs use running → complete | failed | canceled. Headless executions use queued → running → succeeded | failed | canceled (with step / progress while unfinished).

Polling details

• Always GET the Location from the kickoff (or the run or execution you already hold). Same resource for progress and results.
• Wait Retry-After seconds between reads. While unfinished every read answers with it (2 seconds).
• Give up after a few minutes of unfinished status and read once more before you call it lost. A typical run is done in two.
• A run keeps itself moving: when one slice of work runs out of time, it starts the next. A run nobody is driving (a crash, a deploy) is picked up again by the next read, and an hourly sweep is the backstop for runs nobody reads, so keep polling until the run ends.

How many at once

An owner may have 3 runs queued or running at once, and may start 60 an hour. Past either, a start answers 429 (too-many-active or rate-limited) with Retry-After. Finished and canceled runs do not count.

What a result holds

• Product path: results on the run once status is complete.
• Headless: result.shortlist — the homes that fit, best first, each with score, scores, take, pros, cons, commutes and a photo gallery.
• excluded: homes the run graded that did not make the shortlist, each with a category and a reason in a sentence.
• funnel: how many homes each stage kept or dropped.
• notes and credits: every stand-in the run used, and the attribution to show wherever the result is shown.
• compliance: a fair housing checklist, or "not_reviewed" when the reviewer did not run. It is never a clearance.

A headless run's whole pool of considered homes is separately readable for 30 days after it finishes. The result stays forever.

Canceling

Headless: POST .../cancel ends a queued or running execution at once. Product: POST to the run's execution.links.cancel. A call to a provider that was already out may still finish, and what the run spent so far stays on the ledger. Canceling a run that already finished is 409 already-finished.