Async operations

Some work takes longer than a request should. Those endpoints hand you a receipt instead of a result — and you either poll it or let a webhook tell you.

The pattern

An async endpoint returns 202 Accepted with an id and a poll_url. The 202 means we have taken the job, not the job is done. You then poll until the status is terminal.

Importing media from a URL

curl -X POST "https://vm.viraldashboard.io/api/public/v1/brands/412/media/from-url" \
  -H "Authorization: Bearer $VD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/banner.jpg", "asset_type": "image" }'

{
  "data": {
    "job_id": 91,
    "status": "pending",
    "poll_url": "https://vm.viraldashboard.io/api/public/v1/brands/412/jobs/91"
  }
}

Poll it until status is completed or failed:

{
  "data": {
    "job_id": 91,
    "status": "completed",
    "workspace_asset_id": 8814,
    "size_bytes": 148233,
    "error": null
  }
}

workspace_asset_id is the media asset you can now attach to a post. On failed, read error.

Exporting a report

curl -X POST "https://vm.viraldashboard.io/api/public/v1/brands/412/reports/18/export" \
  -H "Authorization: Bearer $VD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "format": "pdf", "start": "2026-06-12", "end": "2026-07-12" }'

That returns a delivery_id. Poll the delivery, and when status is sent download the file:

curl "https://vm.viraldashboard.io/api/public/v1/brands/412/reports/deliveries/77/download" \
  -H "Authorization: Bearer $VD_API_KEY" \
  -o report.pdf

Download before it is ready and you get 409 report_not_ready — that is a "not yet", not a failure. Keep polling.

Polling, without wasting your rate limit

Back off, and give up eventually. Do not spin:

async function waitForJob(brand, jobId, { timeoutMs = 120_000 } = {}) {
  const started = Date.now()
  let delay = 1000

  for (;;) {
    const res = await fetch(`${process.env.VD_API}/brands/${brand}/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${process.env.VD_API_KEY}` },
    })
    const { data } = await res.json()

    if (data.status === 'completed') return data
    if (data.status === 'failed') throw new Error(data.error ?? 'job failed')

    if (Date.now() - started > timeoutMs) throw new Error('timed out waiting for job')

    await new Promise(r => setTimeout(r, delay))
    delay = Math.min(delay * 1.5, 10_000)      // ease off; cap at 10s
  }
}

Better: do not poll at all

Polling burns rate limit to learn nothing most of the time. For publishing, subscribe to post.published and post.failed and we will call you the moment it settles — zero requests spent waiting. See Webhooks.