Skip to main content

​
When Jobs Are Used

For operations that process many items, ScriptBase uses async jobs:
  • Batch transcripts for >50 videos
  • Batch video metadata for >50 videos
  • Website crawling
Instead of waiting for completion, you receive a job ID to poll for status.

​
Job Lifecycle

queued → processing → completed (or failed)
  1. Queued: Job is created and waiting to process
  2. Processing: Job is actively running
  3. Completed: Job finished successfully
  4. Failed: Job encountered an error

​
Creating a Job

Example: Batch transcript request 
curl -X POST "https://api.scriptbase.app/api/v1/transcripts/batch" \
  -H "X-API-Key: sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"videoIds": ["id1", "id2", ...]}'  # >50 videos
Response (HTTP 202 Accepted): 
{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "status": "queued",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

​
Polling Job Status

Use the job ID to check progress: 
curl "https://api.scriptbase.app/api/v1/jobs/job_abc123" \
  -H "X-API-Key: sk_your_key"

​
While Processing

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "status": "processing",
    "progress": 45,
    "total": 100,
    "createdAt": "2024-01-15T10:00:00Z",
    "startedAt": "2024-01-15T10:00:05Z"
  }
}

​
When Complete

{
  "success": true,
  "data": {
    "jobId": "job_abc123",
    "status": "completed",
    "progress": 100,
    "total": 100,
    "output": {
      // Job results here
    },
    "createdAt": "2024-01-15T10:00:00Z",
    "completedAt": "2024-01-15T10:05:30Z"
  }
}

​
Polling Pattern

async function waitForJob(jobId: string, apiKey: string) {
  while (true) {
    const response = await fetch(
      `https://api.scriptbase.app/api/v1/jobs/${jobId}`,
      { headers: { 'X-API-Key': apiKey } }
    );
    
    const { data } = await response.json();
    
    if (data.status === 'completed') {
      return data.output;
    }
    
    if (data.status === 'failed') {
      throw new Error(data.error || 'Job failed');
    }
    
    // Wait 2 seconds before polling again
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

​
Best Practices

Poll every 2-5 seconds. Polling every second wastes rate limit quota.
Set a maximum wait time (e.g., 10 minutes) to avoid infinite loops.
Check for failed status and handle errors appropriately.
Instead of polling, receive a webhook when the job completes.