Jobs & polling

Rendering a video, editing footage, analyzing media and generating 3D take minutes. Those capabilities accept the request, answer immediately with a jobId, and keep working. You collect the result from one endpoint, GET /v1/jobs/{jobId}, whatever capability created the job. Capabilities that return a job include POST /v1/video/render, POST /v1/video/edit, POST /v1/video/edit/approve, POST /v1/video/ugc, POST /v1/video/footage, POST /v1/3d/from-text and POST /v1/3d/from-image. GET /v1/capabilities marks each of them with async: true.

Poll a job

curl https://api.sigmora.org/v1/jobs/job_4k1b7d \
  -H "Authorization: Bearer $SIGMORA_API_KEY"

import os
import random
import time

import requests

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['SIGMORA_API_KEY']}"

TERMINAL = {"done", "cancelled", "failed", "qa_failed"}

def wait_for_job(job_id: str) -> dict:
    while True:
        job = session.get(f"https://api.sigmora.org/v1/jobs/{job_id}", timeout=30).json()["job"]
        if job["status"] in TERMINAL or job["status"] == "awaiting_review":
            return job
        time.sleep(15 + random.random() * 5)

job = wait_for_job("job_4k1b7d")
print(job["status"], job.get("artifacts", {}).get("download"))

const headers = { Authorization: `Bearer ${process.env.SIGMORA_API_KEY}` };
const TERMINAL = new Set(["done", "cancelled", "failed", "qa_failed"]);

async function waitForJob(jobId: string) {
  while (true) {
    const { job } = await fetch(`https://api.sigmora.org/v1/jobs/${jobId}`, { headers }).then((r) => r.json());
    if (TERMINAL.has(job.status) || job.status === "awaiting_review") return job;
    await new Promise((resolve) => setTimeout(resolve, 15_000 + Math.random() * 5_000));
  }
}

const job = await waitForJob("job_4k1b7d");
console.log(job.status, job.artifacts?.download);

Poll every 15–30 seconds and add a little random jitter when you start many jobs at once. A job that belongs to another workspace answers 404 not_found, exactly like one that does not exist.

Job statuses

Branch on status. It is a closed set and safe to switch on. phase is a progress label such as narrating — show it to people, but do not branch on it, because its values change as pipelines evolve.

Status	Meaning
`queued`	Accepted, not started. Keep polling.
`rendering`	In progress. Keep polling.
`awaiting_review`	Footage edits only. A person must approve the proposed cuts; polling will not advance it.
`done`	Terminal. The artifacts are ready.
`cancelled`	Terminal. The job was stopped and will not produce an artifact.
`failed`	Terminal. `error` says why; footage edits also carry a stable `errorCode` and an `errorHint`.
`qa_failed`	Terminal. Rendering finished, but a release check blocked the result. Do not publish it.

awaiting_review waits for a person. A footage edit submitted with reviewCuts: true stops when its cut list is ready. Read the proposed cuts with GET /v1/jobs/{jobId}/proposal, then approve them with POST /v1/video/edit/approve — or let someone review them in the dashboard. See Video, footage & 3D.

A qa_failed result is diagnostic only. Its artifacts are evidence of why the release check failed — read artifacts.scriptReview — not output you can ship. Fix the cause and render again.

A job that ends as failed, cancelled or qa_failed after being charged is refunded. You are never charged for output you cannot release.

Collect the artifacts

When status is done, job.artifacts holds the outputs:

{
  "success": true,
  "job": {
    "id": "job_4k1b7d",
    "kind": "video.render",
    "status": "done",
    "artifacts": {
      "download": "https://api.sigmora.org/render/job_4k1b7d/download/video?exp=1785700000&sig=9f2c",
      "playback": "https://api.sigmora.org/public/job_4k1b7d/master.m3u8",
      "thumbnail": "https://api.sigmora.org/render/job_4k1b7d/download/thumbnail?exp=1785700000&sig=1b7e",
      "srt": "https://api.sigmora.org/render/job_4k1b7d/download/srt?exp=1785700000&sig=c41a",
      "vtt": "https://api.sigmora.org/render/job_4k1b7d/download/vtt?exp=1785700000&sig=77d0",
      "youtube": "...",
      "metadata": "..."
    }
  }
}

Field	What it is
`download`	The finished file. Fetch it directly.
`playback`	A streaming URL (for example HLS) for a player.
`thumbnail`	Poster image.
`srt`, `vtt`	Captions as SubRip and WebVTT.
`youtube`	Title, timestamped chapters, tags and transcript as text, ready to paste into a description.
`metadata`	The same posting data as JSON, for publishing programmatically.
`scriptReview`	The pre-narration script review, including why a release check blocked a job.

A field that is null means that artifact was not produced. Which fields appear depends on kind: a footage edit (video.edit) also carries outputKind, summary and packaging, and while it is awaiting_review, a review block with the size of the pending decision.

Downloading

Render links are signed: fetch them without an Authorization header, from a browser, a downloader or a <video> tag. The bytes come straight from storage, so large files download at full speed. For 3D jobs (kind: "asset.animate"), artifacts.download points at GET /v1/jobs/{jobId}/download. Send your API key and follow the 307 redirect; the redirect target is a short-lived signed URL that needs no key.

curl -L https://api.sigmora.org/v1/jobs/job_4k1b7d/download \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  --output animation.mp4

Signed links expire. Download promptly, and store the job id rather than the URL. Poll the job again whenever you need fresh links.

Follow progress with events

Instead of polling the job, you can read its ordered event log. Each event has a sequence; send the last one you processed as after to resume exactly where you left off.

curl "https://api.sigmora.org/v1/jobs/job_4k1b7d/events?after=0&limit=100" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"

after = 0
while True:
    page = session.get(
        "https://api.sigmora.org/v1/jobs/job_4k1b7d/events",
        params={"after": after, "limit": 100},
        timeout=30,
    ).json()
    for event in page["events"]:
        print(event["sequence"], event["type"], event["status"])
    if page["nextAfter"] is not None:
        after = page["nextAfter"]
    if not page["hasMore"]:
        break

let after = 0;
while (true) {
  const page = await fetch(`https://api.sigmora.org/v1/jobs/job_4k1b7d/events?after=${after}&limit=100`, {
    headers,
  }).then((r) => r.json());
  for (const event of page.events) console.log(event.sequence, event.type, event.status);
  if (page.nextAfter !== null) after = page.nextAfter;
  if (!page.hasMore) break;
}

For a live feed, GET /v1/jobs/{jobId}/stream-token returns a short-lived WebSocket url scoped to the job. If the connection drops, replay from your last sequence with the events endpoint, then reconnect. For delivery to your own server, see Webhooks.

List jobs

GET /v1/jobs lists recent render and footage-edit jobs, newest first. Filter by projectId, kind or status, and page with cursor — see Pagination.

curl "https://api.sigmora.org/v1/jobs?projectId=prj_9x2a4c&status=done&limit=20" \
  -H "Authorization: Bearer $SIGMORA_API_KEY"

Cancel a job

POST /v1/jobs/{jobId}/cancel stops a render, footage edit, media analysis or 3D job. Cancelling is safe to retry: a job that already finished returns its current status. A cancelled job that produced nothing releasable is refunded.

curl -X POST https://api.sigmora.org/v1/jobs/job_4k1b7d/cancel \
  -H "Authorization: Bearer $SIGMORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "No longer needed"}'

result = session.post(
    "https://api.sigmora.org/v1/jobs/job_4k1b7d/cancel",
    json={"reason": "No longer needed"},
    timeout=30,
).json()
print(result["status"])

const result = await fetch("https://api.sigmora.org/v1/jobs/job_4k1b7d/cancel", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ reason: "No longer needed" }),
}).then((r) => r.json());
console.log(result.status);

A late completion can never revive or publish a cancelled job.

When a capability is unavailable

Some capabilities need GPU capacity. When one cannot run, the call is refused up front with 503 capability_unavailable — before you are charged and before any work starts — rather than failing partway. Check available in GET /v1/capabilities before building a flow that depends on it.

Get started

Create

Grow & automate

Integrate

Build reliably

Operate

Poll a job

Job statuses

Collect the artifacts

Downloading

Follow progress with events

List jobs

Cancel a job

When a capability is unavailable

​Poll a job

​Job statuses

​Collect the artifacts

​Downloading

​Follow progress with events

​List jobs

​Cancel a job

​When a capability is unavailable

Poll a job

Job statuses

Collect the artifacts

Downloading

Follow progress with events

List jobs

Cancel a job

When a capability is unavailable