> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.truvo.com/llms.txt.

# Get quote results

`POST /v1/quote-requests` answers right away with `202` and a quote request in the `queued` status. Truvo then gets the quotes in the background, and you read the quote request to see the result.

## Read the quote request

```bash
curl https://api.truvo.com/v1/quote-requests/qreq_... \
  -H "Authorization: Bearer $TRUVO_API_KEY" \
  -H "Prefer: wait=20"
```

A read never starts a new rating run.

## Hold the read open with `Prefer: wait`

Add `Prefer: wait=N` to hold the read open for up to `N` seconds, where `N` is a whole number from 0 to 20. The API answers as soon as the status is no longer `queued` or `running`, or when the time runs out. Without the header, it answers at once.

When the server can't hold the request, it answers at once without `Preference-Applied` and with `Retry-After`. Wait that long before you poll again.

A value that isn't valid gets `422` with the code `invalid_input`.

## Know when to stop

`queued` and `running` mean the work is still going. Every other status is final, so stop reading when you see one. Between reads, the loop waits for the `Retry-After` seconds when the answer has that header, and for 1 second when the server didn't hold the read open:

```bash
while true; do
  body=$(curl -s -D headers.txt "https://api.truvo.com/v1/quote-requests/$QUOTE_REQUEST_ID" \
    -H "Authorization: Bearer $TRUVO_API_KEY" \
    -H "Prefer: wait=20")
  state=$(printf '%s' "$body" | jq -r .status)
  if [ "$state" != "queued" ] && [ "$state" != "running" ]; then
    break
  fi
  retry_after=$(awk -F': ' 'tolower($1) == "retry-after" { print $2 + 0 }' headers.txt)
  if [ -n "$retry_after" ]; then
    sleep "$retry_after"
  elif ! grep -qi '^preference-applied:' headers.txt; then
    sleep 1
  fi
done
printf '%s\n' "$body"
```

## The 60-second deadline

Each quote request has a 60-second deadline. Truvo stops collecting answers 60 seconds after it accepts the request, then finishes the request with the answers it has.

* A carrier that hasn't answered by then reads `no_answer` in `market_outcomes`.
* If no carrier answered at all, the request ends `failed`, and its `failure.code` is `no_quotes_by_deadline`.
* A finished request never reopens. An answer that arrives after the deadline, or after the request finished, doesn't change it.

## Read the result

* **`completeness`** is `pending`, `partial`, or `complete`. A partial result can still be useful.
* **`quotes`** gives the ID and the version of each quote. To read one quote version, call `GET /v1/quotes/{id}?version=`.
* **`market_outcomes`** lists each carrier that Truvo asked, with how it answered: `quote`, `decline`, `missing_information`, `failed`, `unknown`, or `no_answer`. Each entry names the carrier in `source`.
* **`next_actions`** lists what you can do next.
* **`failure`** is `null` unless the request failed. Then it gives a `code`, `no_quotes_by_deadline` or `quote_run_not_started`, with a `message` and a `retry_action`. Both codes ask you to send the request again with a new `Idempotency-Key`.

A `completed` request with zero quotes isn't a failure: a decline, or an answer with no offers, still completes. Check `market_outcomes` to see how each carrier answered.