Async jobs
Today: everything is synchronous
All v1 endpoints currently return results inline within a single HTTP response. There is no queue-and-poll workflow you need to implement.
| Endpoint | Behaviour |
|---|---|
POST /v1/search | Sync. Caps at maxItems = 250. Paginate via nextPageToken for larger result sets. |
POST /v1/search/with-details | Sync. Fans out N parallel detail lookups. |
POST /v1/stays/batch | Sync. Up to 50 entries per call — returns the full Stay array inline. |
POST /v1/listings/{superhost,luxury,instant-book} | Sync. Capped at maxItems = 50. |
For larger workloads, walk pages with nextPageToken (see
Pagination).
Why there’s a /v1/jobs endpoint
The /v1/jobs endpoints exist as scaffolding for a future async path —
queue a job, poll status, fetch results, or get pushed via a job.succeeded
webhook. No public endpoint currently enqueues jobs, so the list will be
empty for fresh accounts. We’ll update this guide when async actually opens
up.
Webhooks
You can still register a webhook today for stay.cached notifications when
a /v1/stays/{id} row is refreshed. See Webhooks.