GET /v1/sora/generations/
Check the current status and progress of your video generation task.
Generation UUID returned from the generate endpoint
Task is in queue waiting to be processed
Video is currently being generated
Video generation completed successfully
Video generation failed with error
curl -X GET https://platform.runblob.io/v1/sora/generations/550e8400-e29b-41d4/ \
-H "Authorization: Bearer YOUR_TOKEN"
Pending
Processing
Completed
Failed
Task is waiting in queue.{
"generation_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"prompt": "A beautiful sunset over the ocean",
"video_url": null,
"created_at": "2025-11-24T10:00:00.000000",
"completed_at": null,
"progress_pct": null,
"progress_pos_in_queue": 3,
"error_message": null
}
Position in the generation queue
Video is being generated.{
"generation_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "processing",
"prompt": "A beautiful sunset over the ocean",
"video_url": null,
"created_at": "2025-11-24T10:00:00.000000",
"completed_at": null,
"progress_pct": 45,
"progress_pos_in_queue": null,
"error_message": null
}
Generation progress from 0 to 100
Video generation completed successfully.{
"generation_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"prompt": "A beautiful sunset over the ocean",
"video_url": "https://cdn.runblob.io/videos/2025/11/550e8400.mp4",
"created_at": "2025-11-24T10:00:00.000000",
"completed_at": "2025-11-24T10:05:30.000000",
"progress_pct": 100,
"progress_pos_in_queue": null,
"error_message": null
}
Direct download URL for the generated video (MP4, H.264)
Generation failed with error.{
"generation_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "failed",
"prompt": "A beautiful sunset over the ocean",
"video_url": null,
"created_at": "2025-11-24T10:00:00.000000",
"completed_at": "2025-11-24T10:02:00.000000",
"progress_pct": null,
"progress_pos_in_queue": null,
"error_message": "Image contains photorealistic people. Please try with a different image."
}
Detailed error message explaining why generation failed
Response Fields
UUID of the generation task
Current status: pending, processing, completed, or failed
Original text prompt used for generation
URL of the generated video (available only when status === "completed")
ISO 8601 timestamp of task creation
ISO 8601 timestamp of completion (or failure)
Generation progress percentage (0-100, only during processing)
Position in queue (only during pending)
Error description (only when status === "failed")
Polling Best Practices
5 seconds - Optimal balance between server load and user experience
- Provides real-time progress updates
- Doesn’t overwhelm the server
- Good UX for users watching progress
15 minutes - Maximum expected generation timeSet a timeout after 180 polling attempts (15 min × 60 sec / 5 sec interval)
Display progress_pct in a progress bar during processing statusShow progress_pos_in_queue when status is pending
Video generation can take 5-15 minutes. Always implement timeout handling and show progress indicators to users.
GET /v1/sora/generations
Get list of all generations for the authenticated user.
Query Parameters
Number of records to return (max 100)
Example Request
curl -X GET "https://platform.runblob.io/v1/sora/generations?limit=20&offset=0" \
-H "Authorization: Bearer YOUR_TOKEN"
Response
[
{
"generation_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "completed",
"prompt": "A beautiful sunset over the ocean",
"video_url": "https://cdn.runblob.io/videos/2025/11/550e8400.mp4",
"created_at": "2025-11-24T10:00:00.000000",
"completed_at": "2025-11-24T10:05:30.000000"
},
{
"generation_id": "650e8400-e29b-41d4-a716-446655440001",
"status": "processing",
"prompt": "City streets at night",
"video_url": null,
"created_at": "2025-11-24T09:50:00.000000",
"completed_at": null
}
]
