Asynchronous search

Receive results when the search is ready

Use async: true for searches that may take longer than your product’s request timeout. The request returns immediately while the search continues.

  • Receive a webhook: Include webhook_url with async: true. Pearch sends a POST to that URL when results are ready, with the same JSON response format as a synchronous search.
  • Show progress: Keep the user informed while the search runs. Show the results when they arrive, then use thread_id for pagination.

Poll for results

  1. On 202 Accepted, save both task_id and thread_id. A cached request can return 200 with results immediately.
  2. Poll GET /v2/search/status/{task_id} until the task reaches a terminal status. Keep the UI in a running state while you wait.
  3. When the status is completed, read the result. Use thread_id to load more results.

The callback adds task metadata to the result. Deduplicate by task_id and use status polling to recover when a callback does not arrive. The webhook contract covers callback authentication, retries, and errors.


Did this page help you?