Async vs Sync

Legacy browser tasks are asynchronous by default. For production integrations, submit the task and store the returned task ID. An optional webhook can report completion; reconcile task state through the API because the callback has at most one admitted delivery attempt.

Use synchronous requests only when the caller can safely wait for a bounded response. Synchronous calls are useful for quick demos, local tools, and short tasks, but long-running browser work should use webhooks or polling.

Recommended flow

1. Submit a task without wait.
2. Store the returned task ID.
3. Receive completion through a webhook when delivery succeeds.
4. Fetch task state and results through the API after a callback or if no callback arrives.

If webhooks are not available, poll task status conservatively. For hosted deployment, avoid polling more than once every 30 seconds. See the callback contract for authentication, delivery limits, and payloads.

When to use wait

Use wait when you expect the task to finish quickly and the client can tolerate holding the HTTP connection open. The maximum wait time is 1,350 seconds. If the task does not complete before the timeout, continue with the asynchronous task ID and fetch the result later.

Member-key task creation commits durable publication intent before optional observation, including with extended retries/admission disabled. Broker failure retains 201 and the task ID for recovery. An observation timeout reports persisted pending/in_progress; unavailable task access/state retains the acceptance snapshot without newly read result content. No-key retries after response loss can still create another task, and existing cancellation/ownership/retention/four-hour timeout limits apply.

Omit wait to select asynchronous submission; wait: 0 makes one immediate observation after acceptance. Configure the client/proxy timeout for positive waits. A task-create response is 201; an event wait on a persistent agent is a different API, capped at 30 seconds, returning 200 even on a timeout. See Timeline and events.

General admission limits

Deployments may enable shared request quotas, concurrent-wait capacity and queued-input backpressure. Accepted replays do not reserve new work capacity; ordinary HTTP quotas still apply. Honor Retry-After on 429/503 and keep the original protected-write key/body. Pending publication remains accepted input and is recovered independently of the caller. Enforced legacy task submission requires omission of wait; shared application/timeline waits remain bounded to 30 seconds. Validate throughput in your own environment.