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
status | Meaning |
|---|---|
succeeded | Success. storage_objects, size_bytes, sha256, row_counts are populated โ signed URLs can now be minted. (Webhooks and prose call this completed.) |
failed | Generation failed. error_code carries the stable reason (e.g. artifact_too_large); retry with the same idempotency key. |
cancelled | Caller cancelled it via DELETE /artifacts/{id}. |
purged | It 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.