Features

Agent reports

Agents and apps can report a wait their user just had. Reports fill places with no live posted wait, are always labelled as reported, and are never taken for ERs or urgent care.

What it is

POST /v1/places/{id}/reports and the report_wait tool store a wait someone actually experienced. Reports are kept apart from posted waits: they are their own tier, agent, and never mixed with an official or place-posted number.

How to report

Send the minutes the user waited, right after the visit. A report needs an API key and counts as one call.

• wait_min: minutes, 0 to 600. Required.
• observed_at: when the user had the wait, ISO 8601 with an offset, within the last 2 hours. Defaults to now.
• kind: in_line while still in line (the wait so far), or done for the whole wait, just finished.

curl -X POST "https://api.waity.ai/v1/places/pl_nvk0wkb3ps/reports" \
  -H "X-Api-Key: $WAITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wait_min":25,"kind":"done"}'

A stored report answers 201 with its report.id and shown. When it isn't shown, reason says why: needs_more_reports, official_wait, closed, too_old or out_of_range.

The MCP tool

report_wait takes the same fields plus the place id. It is the one MCP tool that writes, so its annotations say it isn't read-only.

When reports show

• Only when the place has no usable official or place-posted wait and isn't closed. A live posted wait always wins; the report stays in history.
• Only when at least 2 different people reported or confirmed within the last 45 minutes, or one trusted reporter did (other people confirmed their earlier reports).
• The wait shown is the median of each person's latest report. It stops showing when fewer than 2 people's reports remain in the window.

How they're labelled

A reported wait has now.tier: "agent", now.basis: "reported" and now.source.name: "people", with its own now.source.short. Its summary says it was reported by people ("reported by 2 people") and that the place didn't post it.

Reported minutes are never compared with posted ones: a list with both says so, and instead never offers one as shorter than the other.

Never for ERs or urgent care

A report there is refused with 422 reports_not_accepted, and nothing is stored.

Limits and privacy

• Keyless calls get 401 key_required; they aren't counted.
• One report per reporter per place every 30 minutes (429 report_too_soon, with Retry-After).
• 200 reports per reporter a day (429 report_limit, until midnight UTC).
• Only the key's id is stored with a report. Send no names, phone numbers or other personal data.

Report partners, such as a texting service that reports for many people through one key, can send reporter: a stable one-way hash of each person, never a raw phone number or email. Waity sets up partner keys; any other key's reporter is ignored.

In history

Reports are in history with tier=agent: each report in raw, and hourly or daily figures built the same way as for posted waits.

Related

Reading an answer explains every field of now, and every field of the report route is in the API reference.