Tasks

Some operations can’t finish inside one request because they wait on something slower: a seller that reviews a media buy by hand, or an audience upload that has to be processed. For those, Semicola gives you a task id and you poll the task until it reaches a final state. A task has:

a taskId;
a taskType: audience_sync or media_buy_create;
a status that follows AdCP task states: submitted, working, then a final state;
a resourceType and resourceId naming the record the task works on;
an error message when it fails;
a response with the result once it completes;
a retryAfterSeconds hint for how long to wait before polling again.

Task polling is the only way to follow these operations today. Webhook notifications for tasks aren’t available yet: the buyer webhook subscriptions only carry the discovery.revision event.

All endpoints below are under https://api.semicola.com/api/v2/buyer/.

Where task ids come from

Operation	Where you get the task id
Audience sync (`audience_sync`)	`POST /advertisers/{id}/audiences/sync` answers `202 Accepted` with `taskId` in the body.
Seller review of a buy (`media_buy_create`)	When a seller accepts a buy for review instead of at once, the media buy carries the seller’s task id in `adcpTaskId`.

curl -X POST "https://api.semicola.com/api/v2/buyer/advertisers/12/audiences/sync" \
  -H "Authorization: Bearer $SEMICOLA_API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID" \
  -H "Idempotency-Key: glaze-audiences-2026-11-01" \
  -H "Content-Type: application/json" \
  -d '{ "audiences": [ … ] }'

{
  "data": {
    "success": true,
    "accountId": "12",
    "operationId": "…",
    "taskId": "…"
  },
  "error": null
}

Most reads and ordinary writes are synchronous and never return a task id.

Poll the task

curl "https://api.semicola.com/api/v2/buyer/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SEMICOLA_API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID"

{
  "data": {
    "taskId": "…",
    "taskType": "audience_sync",
    "status": "working",
    "resourceType": "advertiser",
    "resourceId": "12",
    "error": null,
    "response": null,
    "retryAfterSeconds": 5,
    "createdAt": "2026-11-01T14:30:00.000Z",
    "updatedAt": "2026-11-01T14:30:02.481Z"
  },
  "error": null
}

An id that isn’t a task of your account returns 404 NOT_FOUND.

Status values

Status	Meaning	What to do
`submitted`	Accepted, not finished. For a buy: the seller is reviewing it.	Wait `retryAfterSeconds`, then poll again.
`working`	Being processed.	Wait `retryAfterSeconds`, then poll again.
`input-required`	The seller needs something from you.	Read the media buy and answer what the seller asks.
`completed`	Done. `response` holds the result.	Stop polling and read the result.
`rejected`	The seller declined the buy.	Stop polling. The buy is `REJECTED` with the seller’s reason.
`failed`	Permanent failure. `error` says why.	Stop polling; fix the cause before trying again.

Keep polling only while the status is submitted or working. retryAfterSeconds is 5 for an audience sync in progress, 30 for a buy under review, and null once the task is final.

Outcomes by task type

audience_sync. resourceType is advertiser and resourceId is the advertiser id. On completed, response holds the sync result; read the audiences themselves with GET /advertisers/{id}/audiences (or list_audiences over MCP). media_buy_create. resourceType is media_buy and resourceId is the Semicola media buy id (mb_…). The task mirrors the buy’s status: PENDING_APPROVAL reads as submitted, INPUT_REQUIRED as input-required, REJECTED as rejected, FAILED as failed, and any other status as completed. On completed, response is { "media_buy_id": "…" }, the seller’s own id for the buy. error carries the seller’s message when there is one. Semicola follows seller tasks for you: it polls the seller and updates the media buy when the seller decides, so reading the buy (or its campaign’s media buy status) tells you the same thing.

Media buy lifecycle

Every status a buy moves through.

Diagnosing stuck media buys

What to check when a buy doesn’t move.

Start here

Setup

Buy media

Sell media

Guides

Help

Where task ids come from

Poll the task

Status values

Outcomes by task type

Media buy lifecycle

Diagnosing stuck media buys

​Where task ids come from

​Poll the task

​Status values

​Outcomes by task type

​Related

Media buy lifecycle

Diagnosing stuck media buys

Where task ids come from

Poll the task

Status values

Outcomes by task type

Related