Concepts
Batches
One build call's ads, with their statuses and images, read in a single request.
Every POST /v1/campaigns/{id}/ads call returns a batch: a handle on the ads that call started. Poll the batch instead of each ad. ID prefix: batch_. Scope: campaigns:read.
Fields
| Field | Type | Notes |
|---|---|---|
id | string | batch_… |
campaign_id | string | |
ads | array | Every ad of the batch, as image ads |
counts | object | total, processing, completed, failed |
Endpoint
GET /v1/batches/{id}
const { data: batch } = await sal(`/v1/batches/${batchId}`);
if (batch.counts.processing === 0) {
const ready = batch.ads.filter((ad) => ad.status === "completed");
const failed = batch.ads.filter((ad) => ad.status === "failed");
console.log(`${ready.length} ready, ${failed.length} failed`);
}Retried ads join the batch of the ad they replace, so a batch can grow. Each ad also carries its batch_id, and GET /v1/image-ads?batch_id=batch_… lists a batch's ads with the usual filters.