Endpoints

Delivery status

GET https://api.dessert.dev/v1/deliveries/{delivery_id} Try it →

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 processing rendering completed
  • queued — Accepted; not yet picked up by a worker.
  • processing — Copy is being generated and templates assigned.
  • rendering — Statics and (for full format) Luma animations and Remotion videos are being rendered.
  • completed — All ads have static_url values, and for full ads, video_url values.
  • failed — Terminal. The orchestrator gave up; credits have been refunded automatically.

Headers

HeaderDescription
AuthorizationrequiredBearer dsrt_live_…

Path parameters

ParamDescription
delivery_idrequiredThe 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

FieldDescription
delivery_idstringEcho of the path parameter.
statusstringOne of queued, processing, rendering, completed, failed.
raw_statusstringInternal status label. Useful for debugging — don't rely on the values.
ad_countintegerNumber of ad rows currently attached to this delivery.
adsobject[]Array of ad objects. May be empty until processing.
viewer_urlstringHosted web viewer for human review of the delivery.
created_atstringISO 8601 timestamp the delivery was created.

Ad object

FieldDescription
ad_idstringUnique ID for this ad row.
indexintegerPosition within the delivery (1-indexed). Sort by this.
orientationstring"vertical" (1080×1920) or "square" (1080×1350).
headlinestringThe generated headline copy.
static_urlstringHosted PNG/JPG of the static ad. Present once rendering completes.
video_urlstringHosted MP4 of the animated ad. Only present when format="full".
statusstringPer-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

StatusCodeCause
404delivery_not_foundEither the ID is wrong, or the delivery belongs to a different account.
502upstream_errorWe couldn't reach the delivery store. Retry.