Retrieve a rig

GET/v1/rigs/{id}

Returns the current state of a rig job.

Prefer /v1/jobs/

This is an alias kept for convenience. GET /v1/jobs/{id} is the canonical poller and returns the identical object for every operation, so one polling helper covers rigging, generation, and whatever comes next.

Path parameters

Parameter	Description
id	The rig id returned by POST /v1/rigs

Response

200 OK

{
  "id": "8f14e45f-ceea-467a-9c1a-1f0d0e6b7a21",
  "object": "rig",
  "status": "succeeded",
  "model_url": "https://cdn.cinevva.com/rigs/8f14e45f.glb",
  "error": null,
  "created_at": "2026-08-30T19:44:02.113Z",
  "completed_at": "2026-08-30T19:44:29.780Z"
}

Field	Type	Description
status	string	queued, processing, succeeded, or failed
model_url	string | null	CDN URL of the rigged file. Non-null only when succeeded
error	string | null	Why it failed. Non-null only when failed
created_at	string	ISO 8601, UTC
completed_at	string | null	ISO 8601, UTC. Null until terminal

model_url is a direct CDN link and needs no authentication to fetch. Download the file rather than hotlinking it from a live product: URLs are stable but not contractual.

Polling

Poll every 5 seconds for the Fast engine and every 15 to 20 seconds for Pro. Faster polling returns the same answer and spends your rate limit for nothing.

Set your deadline generously. Fast rigs typically finish in 15 to 30 seconds and Pro in up to 150, but a dense mesh can exceed both. A 300-second deadline abandons genuinely stuck jobs without killing slow ones that were about to land.

import time, requests

def wait_for(rig_id, api_key, timeout=300, interval=5):
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.time() + timeout
    while time.time() < deadline:
        job = requests.get(
            f"https://api.cinevva.com/v1/rigs/{rig_id}", headers=headers, timeout=30
        ).json()
        if job["status"] == "succeeded":
            return job["model_url"]
        if job["status"] == "failed":
            raise RuntimeError(job["error"])
        time.sleep(interval)
    raise TimeoutError(f"Rig {rig_id} still {job['status']} after {timeout}s")

Polling is cheap: only POST /v1/rigs spends credits. Poll requests do count against your rate limit, which is why the intervals above are worth respecting.

Errors

Status	Code	Cause
401	unauthorized	Missing or invalid API key
403	forbidden	The rig belongs to another account
404	not_found	No rig with that id