Endpoints
Delivery status
Fetch the current state of a delivery. Use this to poll for completion, or to retrieve the finished assets if you missed the webhook callback.
Lifecycle
Every delivery moves through these states:
- queued — Accepted; not yet picked up by a worker.
- processing — Copy is being generated and templates assigned.
- rendering — Statics and (for
fullformat) Luma animations and Remotion videos are being rendered. - completed — All ads have
static_urlvalues, and for full ads,video_urlvalues. - failed — Terminal. The orchestrator gave up; credits have been refunded automatically.
Headers
| Header | Description |
|---|---|
| Authorizationrequired | Bearer dsrt_live_… |
Path parameters
| Param | Description |
|---|---|
| delivery_idrequired | The delivery_id returned by POST /v1/ads/generate. |
Request
curl
Python
TypeScript
MCP
curl https://api.dessert.dev/v1/deliveries/recXXXXXXXXXXXXXX \
-H "Authorization: Bearer $DESSERT_API_KEY"
import os, time, requests
def wait_for(delivery_id, every=20, timeout=900):
deadline = time.time() + timeout
while time.time() < deadline:
r = requests.get(
f"https://api.dessert.dev/v1/deliveries/{delivery_id}",
headers={"Authorization": f"Bearer {os.environ['DESSERT_API_KEY']}"},
)
body = r.json()
if body["status"] in ("completed", "failed"):
return body
time.sleep(every)
raise TimeoutError(delivery_id)
async function waitFor(id: string, every = 20_000, timeout = 900_000) {
const deadline = Date.now() + timeout;
while (Date.now() < deadline) {
const res = await fetch(`https://api.dessert.dev/v1/deliveries/${id}`, {
headers: { Authorization: `Bearer ${process.env.DESSERT_API_KEY}` },
});
const body = await res.json();
if (body.status === "completed" || body.status === "failed") return body;
await new Promise(r => setTimeout(r, every));
}
throw new Error(`timeout: ${id}`);
}
{
"tool": "dessert.get_delivery",
"arguments": { "delivery_id": "recXXXXXXXXXXXXXX" }
}
Response
| Field | Description |
|---|---|
| delivery_idstring | Echo of the path parameter. |
| statusstring | One of queued, processing, rendering, completed, failed. |
| raw_statusstring | Internal status label. Useful for debugging — don't rely on the values. |
| ad_countinteger | Number of ad rows currently attached to this delivery. |
| adsobject[] | Array of ad objects. May be empty until processing. |
| viewer_urlstring | Hosted web viewer for human review of the delivery. |
| created_atstring | ISO 8601 timestamp the delivery was created. |
Ad object
| Field | Description |
|---|---|
| ad_idstring | Unique ID for this ad row. |
| indexinteger | Position within the delivery (1-indexed). Sort by this. |
| orientationstring | "vertical" (1080×1920) or "square" (1080×1350). |
| headlinestring | The generated headline copy. |
| static_urlstring | Hosted PNG/JPG of the static ad. Present once rendering completes. |
| video_urlstring | Hosted MP4 of the animated ad. Only present when format="full". |
| statusstring | Per-ad status (e.g. rendered, queued). |
Example response
{
"delivery_id": "recXXXXXXXXXXXXXX",
"status": "completed",
"raw_status": "5. Delivered",
"ad_count": 6,
"ads": [
{
"ad_id": "recAAAAAAAAAAAAAA",
"index": 1,
"orientation": "vertical",
"headline": "Glass skin, on the first morning",
"static_url": "https://cdn.dessert.dev/.../ad-1-vrt.png",
"video_url": "https://cdn.dessert.dev/.../ad-1-vrt.mp4",
"status": "rendered"
},
{
"ad_id": "recBBBBBBBBBBBBBB",
"index": 1,
"orientation": "square",
"headline": "Glass skin, on the first morning",
"static_url": "https://cdn.dessert.dev/.../ad-1-sq.png",
"video_url": "https://cdn.dessert.dev/.../ad-1-sq.mp4",
"status": "rendered"
}
],
"viewer_url": "https://app.dessert.dev/viewer/recXXXXXXXXXXXXXX",
"created_at": "2026-05-19T18:24:01.000Z"
}
Polling cadence
Poll every 15–30 seconds. Statics generally finish in 2–4 minutes; full
deliveries in 6–9 minutes. If you need exact callbacks, use
webhooks instead.
Errors
| Status | Code | Cause |
|---|---|---|
| 404 | delivery_not_found | Either the ID is wrong, or the delivery belongs to a different account. |
| 502 | upstream_error | We couldn't reach the delivery store. Retry. |