Async Jobs

How to handle long-running operations like trend scans, competitor analysis, thumbnail generation, and transcription.

Async Operations

Some Soke API operations take longer to complete and run asynchronously. Instead of blocking until done, these endpoints return a job ID that you poll for results.

Async endpoints

Endpoint	Operation
`GET /api/v1/trends/scan`	Trend scanning
`POST /api/v1/competitor/analyze`	Competitor analysis
`POST /api/v1/thumbnail/generate`	AI thumbnail generation
`POST /api/v1/thumbnail/generate-background`	Background generation
`POST /api/v1/transcription`	Video/audio transcription

How it works

Step 1: Start the job

curl -X POST https://api.usesoke.ai/api/v1/competitor/analyze \
  -H "Content-Type: application/json" \
  -H "X-Soke-Key: sk_live_your_api_key" \
  -d '{
    "channelUrl": "https://youtube.com/@competitor",
    "platform": "youtube"
  }'

Response:

{
  "success": true,
  "data": {
    "jobId": "job_abc123def456",
    "status": "queued",
    "estimatedCompletionSeconds": 30
  },
  "meta": {
    "platform": "youtube",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "processing_time_ms": 85
  }
}

Step 2: Poll for results

Use the job ID to check status:

curl https://api.usesoke.ai/api/v1/jobs/job_abc123def456 \
  -H "X-Soke-Key: sk_live_your_api_key"

Pending response:

{
  "success": true,
  "data": {
    "jobId": "job_abc123def456",
    "status": "processing",
    "progress": 60
  }
}

Completed response:

{
  "success": true,
  "data": {
    "jobId": "job_abc123def456",
    "status": "completed",
    "result": {
      // Operation-specific results
    }
  }
}

Job statuses

Status	Description
`queued`	Job is waiting to be processed
`processing`	Job is currently running
`completed`	Job finished successfully — results in `data.result`
`failed`	Job failed — error details in `data.error`

Polling best practices

Do not poll more frequently than once every 2 seconds. Excessive polling may trigger rate limiting.

Recommended polling strategy:

async function pollJob(jobId, apiKey) {
  const maxAttempts = 60;
  const intervalMs = 3000;

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.usesoke.ai/api/v1/jobs/${jobId}`,
      { headers: { 'X-Soke-Key': apiKey } }
    );
    const { data } = await response.json();

    if (data.status === 'completed') return data.result;
    if (data.status === 'failed') throw new Error(data.error?.message);

    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }

  throw new Error('Job timed out');
}

import time
import requests

def poll_job(job_id, api_key, max_attempts=60, interval=3):
    for _ in range(max_attempts):
        response = requests.get(
            f'https://api.usesoke.ai/api/v1/jobs/{job_id}',
            headers={'X-Soke-Key': api_key},
        )
        data = response.json()['data']

        if data['status'] == 'completed':
            return data['result']
        if data['status'] == 'failed':
            raise Exception(data.get('error', {}).get('message', 'Job failed'))

        time.sleep(interval)

    raise Exception('Job timed out')

Credits for async jobs

Credits are charged when you start the job, not when it completes. If a job fails due to a server error, credits are automatically refunded.