How should we handle long-running SOS searches? What does “Incomplete” mean?

When a state takes longer than ~20 seconds to return results, Cobalt responds with:

{  
"status":"Incomplete",
"statusCode":202,  
"retryId":"<id>",  
"message":"State is taking longer to acquire the data. Use this retryId to check back in for your data."
}

This does not mean the lookup failed — it means the search is still processing in the background.

You have two options to retrieve the final results:

• Polling
  Save the retryId and call the status endpoint until the data is ready.
• Webhooks (recommended)
  Provide a callbackUrl. In this case:
  • Cobalt will immediately reply with a requestId.
  • No results are ever returned directly in this initial response.
  • When processing is complete, Cobalt will POST the finished results back to your callbackUrl, including the same requestId so you can tie it to the original request.

‍