​
Execution Modes

ModelBeam is an asynchronous API. When you submit a job, you receive a request_id immediately. The actual processing happens in the background, and you can receive results through three methods.

​
Job Lifecycle

Every job follows this lifecycle: 
pending → processing → done | error
  1. pending — Job is queued and waiting for a worker
  2. processing — Job is being processed by a GPU worker
  3. done — Job completed successfully, results are available
  4. error — Job failed (see error code for details)

​
Result Delivery Methods

​
1. Polling (Simplest)

Poll the status endpoint until the job is complete. 
GET /api/v1/client/request-status/{request_id}

import requests
import time

def poll_job(api_key, request_id, interval=2, timeout=300):
    url = f"https://api.modelbeam.ai/api/v1/client/request-status/{request_id}"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "application/json"
    }
    start = time.time()
    while time.time() - start < timeout:
        resp = requests.get(url, headers=headers)
        resp.raise_for_status()
        data = resp.json()["data"]

        if data["status"] == "done":
            return data
        if data["status"] == "error":
            raise Exception(f"Job {request_id} failed")

        progress = data.get("progress", 0)
        if progress > 50:
            time.sleep(interval)
        else:
            time.sleep(interval * 2)

    raise TimeoutError(f"Job {request_id} timed out after {timeout}s")

​
2. Webhooks (Server-to-Server)

Provide a webhook_url parameter in your request. ModelBeam will send HTTP POST callbacks when the job status changes. Best for server-side integrations. See the Webhooks guide for details.

​
3. WebSockets (Real-time)

Connect to the Pusher-compatible WebSocket server for real-time status updates. Best for client-side applications that need live progress updates. See the WebSockets guide for details.

​
Response Format

All status responses share this format: 
{
  "data": {
    "status": "done",
    "preview": "base64_string_or_null",
    "result_url": "https://storage.modelbeam.ai/...",
    "results_alt_formats": null,
    "result": null,
    "progress": 100.0
  }
}
FieldDescription
statusJob status: pending, processing, done, error
previewBase64-encoded thumbnail (available during processing and on completion)
result_urlURL to download the generated file (images, audio, video)
results_alt_formatsAlternative format URLs (jpg, webp) when available
resultText output for transcription/OCR endpoints
progressCompletion percentage (0-100)