Wait for a lookup to change

Holds the request until the lookup changes or for at most about 25 seconds. Reconnect with the last X-Lookup-Cursor value as after; this avoids frequent browser polling while preserving the same Lookup response shape.

A 200 carries no Retry-After: while the lookup is not final, reconnect at once with the new cursor. Hold only one wait per lookup. A second concurrent wait for the same lookup from the same address, or more waits than the service will hold at once, answers 429 rate_limited with Retry-After.

get/lookups/{lookup_id}/wait

Request

  • Base URL: https://whenisbins.com/v1
  • URL: https://whenisbins.com/v1/lookups/{lookup_id}/wait
  • Auth: one of:
    • none
    • HTTP bearer

Path parameters

lookup_idstring uuid required

Query parameters

afterstring

Opaque cursor returned by the preceding response.

Response

Current state, returned when it changes or the hold expires.

idstring uuid required
status'queued' | 'running' | 'partial' | 'done' | 'failed' required

partial = a usable result is attached while fuller dates (ICS/PDF completion) are still being fetched — check each collection's dates_complete.

created_atstring date-time required
expected_wait_secondsinteger nullable required

Route-aware recent cold-visit p90, rounded up to seconds. Fast deterministic routes supply the initial estimate when they serve at least half of recent cold visits; a deterministic miss promotes the lookup to at least 120 for the browser handoff. Null until five timed cold observations exist in the rolling 84-day window. While the route maintainer's control plane holds the council's active deterministic route healthy, the deterministic-stage estimate is instead the p90 of recent cold successes on the fast routes alone (null below five such successes), whatever the blended history or success rate says. A lookup parked for the residential worker after a council bot-blocked the web host is estimated from that worker's own deterministic stage timing (pickup plus execution, p90) from its first recent sample; with none it shows the handoff.

success_ratenumber double nullable required

Share of cold observations with outcome success in the same rolling window. Null until five eligible cold observations exist. Cache hits are never included.

completed_atstring date-time nullable
problemstring

Present when status is failed (same codes as Problem).

detailstring

Citizen-actionable explanation when failed.

Changes

No recorded changes to this operation across all 1 revision of this API.