UGCLabUGCLab

Job Status

Monitor and manage UGC generation jobs

Monitor and manage UGC generation jobs.

Base URL

https://api.ugclab.app/api/v1

Get Job Status

Retrieve the current status of a UGC generation job.

GET /ugc/{ugcId}

Path Parameters

ParameterTypeDescription
ugcIdstringThe UGC job ID (returned when creating a job)

Response

{
  "data": {
    "id": "clxxx...",
    "status": "PROCESSING",
    "progress": 45,
    "videoUrl": null,
    "processingSteps": {
      "refineScript": "completed",
      "refineActions": "completed",
      "videoGeneration": "pending"
    },
    "actor": {
      "id": "clactor123...",
      "name": "Sarah"
    },
    "isCustomActor": false,
    "model": "talking-actor-pro-15sec",
    "creditsCharged": 125,
    "creditsRefunded": 0,
    "errorMessage": null,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:32:00.000Z"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-15T10:32:30.000Z"
  }
}

Response Fields

FieldTypeDescription
idstringUGC job ID
statusstringCurrent status (see Status Values below)
progressnumberProgress percentage (0-100)
videoUrlstringVideo download URL (only when completed)
processingStepsobjectDetailed step-by-step progress
actorobjectActor information (null for custom actors)
isCustomActorbooleanWhether this uses a custom actor definition
modelstringVideo model used
creditsChargednumberCredits charged for this job
creditsRefundednumberCredits refunded (if cancelled)
errorMessagestringError details (only when failed)
createdAtstringISO 8601 creation timestamp
updatedAtstringISO 8601 last update timestamp

Status Values

StatusDescription
PENDINGJob is queued and waiting to start
PROCESSINGJob is actively being processed
SAVINGVideo is being saved and uploaded
COMPLETEDJob finished successfully, video available
FAILEDJob failed, check errorMessage for details

Processing Steps

The processingSteps object shows the status of each step:

Step StatusDescription
pendingStep not yet started
completedStep finished successfully
skippedStep was not needed
failedStep failed

Cancel Job

Cancel a pending job and receive a credit refund.

DELETE /ugc/{ugcId}

Path Parameters

ParameterTypeDescription
ugcIdstringThe UGC job ID to cancel

Response

{
  "data": {
    "id": "clxxx...",
    "status": "CANCELLED",
    "creditsRefunded": 125
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2025-01-15T10:35:00.000Z"
  }
}

Cancellation Rules

Only PENDING jobs can be cancelled. Jobs that are already PROCESSING, COMPLETED, or FAILED cannot be cancelled.

  • Only PENDING jobs can be cancelled
  • PROCESSING jobs cannot be cancelled (already in progress)
  • COMPLETED and FAILED jobs cannot be cancelled
  • Credits are automatically refunded upon successful cancellation

Examples

# Check job status
curl -X GET "https://api.ugclab.app/api/v1/ugc/clxxx123" \
  -H "Authorization: Bearer ugc_your_api_key"

# Cancel a pending job
curl -X DELETE "https://api.ugclab.app/api/v1/ugc/clxxx123" \
  -H "Authorization: Bearer ugc_your_api_key"
async function waitForCompletion(ugcId: string, apiKey: string): Promise<string> {
  const maxAttempts = 60; // 5 minutes with 5s intervals

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.ugclab.app/api/v1/ugc/${ugcId}`,
      {
        headers: { 'Authorization': `Bearer ${apiKey}` },
      }
    );

    const data = await response.json();
    const status = data.data.status;

    console.log(`Status: ${status}, Progress: ${data.data.progress}%`);

    if (status === 'COMPLETED') {
      return data.data.videoUrl;
    }

    if (status === 'FAILED') {
      throw new Error(data.data.errorMessage);
    }

    // Wait 5 seconds before next check
    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  throw new Error('Timeout waiting for completion');
}

// Usage
const videoUrl = await waitForCompletion('clxxx123', 'ugc_your_api_key');
console.log('Video ready:', videoUrl);
import requests
import time

def wait_for_completion(ugc_id: str, api_key: str, timeout: int = 300) -> str:
    headers = {'Authorization': f'Bearer {api_key}'}
    start_time = time.time()

    while time.time() - start_time < timeout:
        response = requests.get(
            f'https://api.ugclab.app/api/v1/ugc/{ugc_id}',
            headers=headers
        )
        data = response.json()['data']

        print(f"Status: {data['status']}, Progress: {data['progress']}%")

        if data['status'] == 'COMPLETED':
            return data['videoUrl']

        if data['status'] == 'FAILED':
            raise Exception(data['errorMessage'])

        time.sleep(5)

    raise TimeoutError('Timeout waiting for completion')

# Usage
video_url = wait_for_completion('clxxx123', 'ugc_your_api_key')
print(f'Video ready: {video_url}')

Instead of polling, configure webhooks to receive real-time status updates.

EventDescription
ugc_createdJob queued
ugc_processingJob started processing
ugc_completedJob finished, video ready
ugc_failedJob failed

Error Codes

CodeHTTP StatusDescription
UGC_NOT_FOUND404UGC job not found or not in your workspace
UGC_ALREADY_COMPLETED400Cannot cancel completed job
UGC_ALREADY_FAILED400Cannot cancel failed job
UGC_PROCESSING400Cannot cancel job in progress
RATE_LIMIT_EXCEEDED429Too many requests
INTERNAL_ERROR500Internal server error

See Authentication for authentication-related errors.

On this page