Skip to main content
GET
Get quote-request batch status
Reads a batch you opened with create a quote-request, and the quotes collected for it so far. If you lost the create response, you don’t need this id to recover: re-send the same request and its request_id returns the original batch. See Idempotency.

Path Parameters

quoteRequestId
string
required

The ID of the quote-request batch to query

Response

Quote-request status retrieved successfully

Response to GET /v1/payments/quote-requests/{quoteRequestId}. The status enum describes the quote-request batch lifecycle and is disjoint from the payment-status enum.

quote_request_id
string
required
Example:

"qr_a1b2c3d4-5678-90ef-1234-567890abcdef"

status
enum<string>
required

Derived batch lifecycle, computed at read time (not a stored state machine). Disjoint from the payment-status enum returned by the award and payment-status endpoints.

  • collecting — collection window still open; quotes lists those collected so far (a quote is awardable from arrival, by its own award_deadline; more may arrive until collection_close).
  • ready — collection complete; none awarded yet; either at least one quote is still within its award_deadline, or no settler bid (empty quotes array — the successful "no quotes available" result).
  • awarded — a quote produced a payment row; no further awards accepted (MVP).
  • expired — collection closed, nothing awarded, and every collected quote is now past its award_deadline ("quotes lapsed"). An empty batch is ready, not expired — the two are deliberately distinct ("no quotes available" vs "quotes lapsed").
Available options:
collecting,
ready,
awarded,
expired
Example:

"awarded"

quotes
object[]

Collected quotes with award linkage — those collected so far while collecting, the full set once the window closes.

payments
object[]

Flat list of awarded (quote_id, payment_id) pairs. At most one entry under MVP single-award.

requested_count
integer

How many agents the request was broadcast to. The only auction count that is not derivable from the rest of this response:

  • quoted = quotes length
  • declined = sum of decline_summary[].count
  • participated = quoted + declined
  • silent = requested_count - participated

Silence and a decline are different signals, which is why the denominator is surfaced rather than left implicit.

ABSENT when the number is unknown, which happens when the broadcast count was never recorded or when the auction detail could not be read. Absence means unknown, never zero, so silent is derivable only when this field is present.

Example:

8

decline_summary
object[]

Why the request drew few or no quotes, so a caller can tell "nobody can fund this right now" from "my request was malformed".

EXHAUSTIVE over agents: every agent that declined is counted exactly once, under its most recent reason, so the counts sum to the number of agents that declined. An agent that declined more than once with different reasons is counted once, not once per reason.

Empty means nobody declined. ABSENT means the auction detail could not be read, so the breakdown is unknown. While status is collecting it is provisional, because agents are still responding.

The free-form decline detail is never relayed, because that detail carries an agent's balances and would let a caller map inventory by polling cheap quote-requests across corridors.