Polling for status - TrueFan API

Every generate call returns a job reference immediately, before rendering finishes. Use the status endpoints to check progress — or better, use a webhook so you don’t have to poll at all.

The whole job

curl "https://dev-backend-ai.truefans.in/api/external/v1/bulk-jobs/{bulk_job_id}/status/" \
  -H "Authorization: Bearer $TRUEFAN_API_KEY"

A job’s own status reflects every row as a whole. summary.pending tells you how many rows are still in flight — poll until it reaches zero, then check csv_ready and download the CSV export for every row’s result.

One video

While a batch is still processing, check a specific row using the external_id you supplied for it — you won’t have TrueFan’s own generation_id until the batch is done:

curl "https://dev-backend-ai.truefans.in/api/external/v1/bulk-jobs/{bulk_job_id}/generations/{external_id}/status/" \
  -H "Authorization: Bearer $TRUEFAN_API_KEY"

status is one of pending, processing, success, failed. Once it reaches success, result_video_url and thumbnail_url are populated. Once failed, error_message explains why. Once the batch is done, download the CSV export instead — it has every row’s result, not just one, in a single request.

A simple polling loop

import time
import requests

def wait_for_batch(bulk_job_id, api_key, timeout_s=300, interval_s=3):
    url = f"https://dev-backend-ai.truefans.in/api/external/v1/bulk-jobs/{bulk_job_id}/status/"
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.monotonic() + timeout_s

    while time.monotonic() < deadline:
        resp = requests.get(url, headers=headers)
        resp.raise_for_status()
        data = resp.json()
        if data["csv_ready"]:
            return data
        time.sleep(interval_s)

    raise TimeoutError(f"bulk job {bulk_job_id} did not finish in {timeout_s}s")

Polling too aggressively (sub-second intervals) doesn’t make a render finish faster — a few seconds between checks is plenty. Prefer a webhook over polling entirely where you can.