Get Status

GET /shorts/:id/status

Returns the current processing status and progress of a short creation request. Use this endpoint to poll for completion after submitting a request via POST /shorts/create.

Path parameters

Request

curl -H "X-API-Key: sk_ssemble_your_key" \
  https://aiclipping.ssemble.com/api/v1/shorts/665a1b2c3d4e5f6a7b8c9d0e/status

Response

While processing

{
  "data": {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "status": "processing",
    "step": "finding_highlights",
    "stepMessage": "Finding interesting segments...",
    "progress": 60,
    "userEmail": "user@example.com",
    "isDemo": false
  }
}

When failed

{
  "data": {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "status": "failed",
    "step": "failed",
    "stepMessage": "Processing failed",
    "progress": 0,
    "userEmail": "user@example.com",
    "failureReason": "Video download failed",
    "isDemo": false
  }
}

Response fields

Note: The failureReason field is only included in the response when the status is failed. For all other statuses (queued, processing, completed, cancelled), this field is absent from the response.

Status values

The status field transitions through these states during processing:

Processing steps

The step field provides granular detail about what is currently happening during processing. Use the stepMessage field to display a human-readable label to your users.

Status flow

queued → processing → completed
                   ↘ failed

Requests start in queued, transition to processing once a worker picks them up, and end in either completed or failed. A request can be cancelled at any point before completion.

Polling strategy

We recommend polling every 10 seconds until the status is a terminal state (completed, failed, or cancelled). Processing typically takes 5–30 minutes depending on:

• Video length — longer source videos take more time to download and transcribe
• Queue position — during peak hours, requests may wait longer in the queue
• Options selected — overlays (game video, meme hooks) add rendering time

Recommended polling implementation

async function waitForCompletion(requestId, apiKey) {
  const POLL_INTERVAL = 10000; // 10 seconds
  const MAX_POLL_TIME = 45 * 60 * 1000; // 45 minutes max
  const startTime = Date.now();
 
  while (Date.now() - startTime < MAX_POLL_TIME) {
    const res = await fetch(
      `https://aiclipping.ssemble.com/api/v1/shorts/${requestId}/status`,
      { headers: { 'X-API-Key': apiKey } }
    );
    const { data } = await res.json();
 
    console.log(`${data.stepMessage} (${data.progress}%)`);
 
    switch (data.status) {
      case 'completed':
        return data;
      case 'failed':
        throw new Error(`Processing failed: ${data.failureReason}`);
      case 'cancelled':
        throw new Error('Request was cancelled');
      default:
        // Still queued or processing — wait and retry
        await new Promise(r => setTimeout(r, POLL_INTERVAL));
    }
  }
 
  throw new Error('Polling timed out after 45 minutes');
}

What to do with each status

Polling best practices

• Poll interval: 10 seconds is the recommended minimum. Polling more frequently wastes API calls and may trigger rate limits.
• Timeout: Set a maximum polling duration (e.g., 45 minutes). If a request hasn't completed by then, it likely encountered an issue.
• Show step details: Use stepMessage to display what the system is currently doing (e.g., "Analyzing video...") alongside the progress percentage.
• Handle all terminal states: Always check for failed and cancelled in addition to completed.
• Rate limits: Status polling uses the "status check" rate limiter. See Rate Limits for details.

Error responses

Common failure reasons

When a request fails, the failureReason field provides details. Common reasons include:

If a request fails, you can retry by creating a new request with the same parameters. Failed requests still consume credits.