Jobs (async model)

Any operation that can take more than a moment — building a store, publishing, attaching a domain, bulk imports, sending a campaign, syncing ads — is asynchronous. It returns 202 with a job reference instead of blocking:

{ "success": true, "data": { "job_id": "…", "status": "queued", "poll": "/agent/v1/jobs/…" } }

Polling

Read a job’s live status — non-terminal jobs are re-resolved against the underlying subsystem on each read:

curl https://api.platformdtc.com/api/v1/agent/v1/jobs/$JOB_ID -H "X-Agent-Key: sq_agt_xxx"

Or block until it finishes (server-side long-poll, up to timeout_seconds, max 600):

curl "https://api.platformdtc.com/api/v1/agent/v1/jobs/$JOB_ID/wait?timeout_seconds=120" \
  -H "X-Agent-Key: sq_agt_xxx"

List recent jobs for the merchant (filter by status, kind):

curl "https://api.platformdtc.com/api/v1/agent/v1/jobs?status=running&page=1&limit=20" \
  -H "X-Agent-Key: sq_agt_xxx"

Status values

Status	Meaning
`queued`	accepted, not started
`running`	in progress
`succeeded`	done — see `result`
`failed`	error — see `error`
`cancelled`	cancelled (see `POST /jobs/{id}/cancel`)
`pending_approval`	waiting on a human (Approvals)

A terminal job’s result carries the payload you want — e.g. project_id, production_url, created product ids, or send stats.

From an agent, every async tool is followed by dtc_job_wait. See the Playbook.

Overview

Merchant guides

Fundamentals

Polling

Status values

​Polling

​Status values

Polling

Status values