> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Async jobs and result availability

> Poll V1 jobs reliably and handle their lifecycle.

Characters and Motions are reusable asynchronous assets. Renders and 3D Conversion requests are asynchronous operations that deliver artifacts.

## Status lifecycle

```mermaid theme={null}
stateDiagram-v2
  [*] --> queued
  queued --> processing
  processing --> ready
  processing --> failed
  processing --> cancelled
```

`cancelled` applies to Render state; clients should treat it as terminal. Poll every 3–5 seconds while a resource is `queued` or `processing`. Stop polling for `ready`, `failed`, or `cancelled`.

## Polling example

```python theme={null}
import time
import requests

def wait_for_resource(url, api_key, interval_seconds=3):
    headers = {"Authorization": f"Bearer {api_key}"}
    while True:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        resource = response.json()

        if resource["status"] == "ready":
            return resource
        if resource["status"] in {"failed", "cancelled"}:
            error = resource.get("error") or {}
            raise RuntimeError(
                f"{resource['status']}: {error.get('code')} {error.get('message')}"
            )
        time.sleep(interval_seconds)

render = wait_for_resource(
    "https://apis.viggle.ai/v1/renders/render_123abc",
    "YOUR_API_KEY",
)
print(render["video_url"])
```

## Render progress

Render responses can include:

* `progress`: an integer from 0 to 100
* `stage`: `analyzing`, `rendering`, or `finishing`
* `video_url`: available only when the Render is ready
* `alpha_url`: available with transparent output

## Download promptly

Completed result URLs and task state are retained for one hour. Persist output in your own storage if it is needed later.

## Recover safely

* For `failed`, inspect `error.code` and follow its suggested recovery path.
* Do not retry a Render blindly after a network timeout: V1 does not currently expose idempotency keys. If a create response was received, query its known resource ID; otherwise resolve the outcome with your request logs and `X-Request-Id` before submitting again.
* Include `X-Request-Id` in support requests.