How-to guideApplies to: Unified engine deployments
Many execute APIs accept work before it finishes. HTTP 202 means acceptance, not successful SQL, table publication, or notification delivery.
Follow the identity
- Submit the request once and retain its IDs.
- Read the related operation, run, snapshot, or turn status.
- Wait for the relevant final state.
- Inspect failures and commit evidence.
- Read results only when they are ready.
Complete examples carry returned IDs into later requests. Send the status request to read its latest state. Repeat that read until execution finishes. Reading status does not change engine execution.
Read states in context
SQL operations, workload runs, notebook runs, dashboard refreshes, and assistant turns have different state enums. Use the response schema for that API. Do not treat every state named Running as an allocated SQL worker: a sensor can be waiting without one.
OutcomeUnknown is not proof of failure. Inspect the original attempt and commit evidence before starting replacement writes.
Cancel explicitly
Use the cancellation or interruption operation for the resource you started. Cancellation can itself be asynchronous. Follow the final state rather than assuming an accepted cancel request has already stopped all work.
Stopping local polling, stopping an event stream, closing the docs, or aborting a browser fetch does not cancel engine work. A confirmed table commit is not rolled back by cancellation.Last modified on November 4, 2026
