Job Status
Monitor and manage UGC generation jobs
Monitor and manage UGC generation jobs.
Base URL
https://api.ugclab.app/api/v1Get Job Status
Retrieve the current status of a UGC generation job.
GET /ugc/{ugcId}Path Parameters
| Parameter | Type | Description |
|---|---|---|
ugcId | string | The 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
| Field | Type | Description |
|---|---|---|
id | string | UGC job ID |
status | string | Current status (see Status Values below) |
progress | number | Progress percentage (0-100) |
videoUrl | string | Video download URL (only when completed) |
processingSteps | object | Detailed step-by-step progress |
actor | object | Actor information (null for custom actors) |
isCustomActor | boolean | Whether this uses a custom actor definition |
model | string | Video model used |
creditsCharged | number | Credits charged for this job |
creditsRefunded | number | Credits refunded (if cancelled) |
errorMessage | string | Error details (only when failed) |
createdAt | string | ISO 8601 creation timestamp |
updatedAt | string | ISO 8601 last update timestamp |
Status Values
| Status | Description |
|---|---|
PENDING | Job is queued and waiting to start |
PROCESSING | Job is actively being processed |
SAVING | Video is being saved and uploaded |
COMPLETED | Job finished successfully, video available |
FAILED | Job failed, check errorMessage for details |
Processing Steps
The processingSteps object shows the status of each step:
| Step Status | Description |
|---|---|
pending | Step not yet started |
completed | Step finished successfully |
skipped | Step was not needed |
failed | Step failed |
Cancel Job
Cancel a pending job and receive a credit refund.
DELETE /ugc/{ugcId}Path Parameters
| Parameter | Type | Description |
|---|---|---|
ugcId | string | The 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
PENDINGjobs can be cancelled PROCESSINGjobs cannot be cancelled (already in progress)COMPLETEDandFAILEDjobs 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}')Webhooks (Recommended)
Instead of polling, configure webhooks to receive real-time status updates.
| Event | Description |
|---|---|
ugc_created | Job queued |
ugc_processing | Job started processing |
ugc_completed | Job finished, video ready |
ugc_failed | Job failed |
Error Codes
| Code | HTTP Status | Description |
|---|---|---|
UGC_NOT_FOUND | 404 | UGC job not found or not in your workspace |
UGC_ALREADY_COMPLETED | 400 | Cannot cancel completed job |
UGC_ALREADY_FAILED | 400 | Cannot cancel failed job |
UGC_PROCESSING | 400 | Cannot cancel job in progress |
RATE_LIMIT_EXCEEDED | 429 | Too many requests |
INTERNAL_ERROR | 500 | Internal server error |
See Authentication for authentication-related errors.