02 Poll Artifact Until Completed

Step 2: Poll until completed

Generation is asynchronous. Re-send GET /artifacts/{{ad_artifact_id}} until status is terminal. Space polls by the retryAfterSeconds hint from Step 1 (or subscribe to the artifact.completed webhook instead of polling).

What this step does

It reads the artifact resource and checks how far generation has progressed. A read while the job is still running returns the same resource with status: "processing" and the terminal fields still null; once generation finishes it flips to a terminal status and the download-related fields (storage_objects, size_bytes, sha256, row_counts) fill in.

Why it's needed

You cannot mint download URLs until the artifact is succeeded โ€” there are no files to sign before then (Step 3 returns 409 artifact_not_completed if you try early). This step is the gate: it confirms the bundle actually exists and, on failed, tells you why via error_code so you don't blindly retry a request that will always fail (e.g. artifact_too_large). It also surfaces sha256 / row_counts, so you can verify the snapshot before handing it downstream.

Poll or webhook โ€” which to choose

  • Poll (this step) when the caller is a script that wants to block until the file is ready โ€” simplest for a linear pipeline.
  • Webhook (artifact.completed / artifact.failed) when you'd rather not hold a polling loop open โ€” subscribe and react when the event fires. The webhook carries no download URL, so you still mint in Step 3.

Either way, honour retryAfterSeconds (don't hammer the endpoint) and treat only the states below as terminal.

Terminal states

statusMeaning
succeededSuccess. storage_objects, size_bytes, sha256, row_counts are populated โ€” signed URLs can now be minted. (Webhooks and prose call this completed.)
failedGeneration failed. error_code carries the stable reason (e.g. artifact_too_large); retry with the same idempotency key.
cancelledCaller cancelled it via DELETE /artifacts/{id}.
purgedIt succeeded, and its files have since aged out of retention. purged_at says when and action_required is regenerate; nothing can be downloaded or minted. Only reachable for an id you held for months.

While queued / processing, the terminal fields are null / empty โ€” see the second example.

Next Step

โ†’ Step 3: Mint Signed URLs.