Jobs

All async operations (renders, transcriptions, video operations) return a jobId. Use the Jobs API to poll status, download results, and manage your queue.

Get Job Status

GET /api/jobs/:jobId

Path Parameters:

• jobId — job ID from any async operation

Headers:

• X-API-Key: <your-api-key> (required)

Job Status Values:

Status	Meaning
queued	Waiting in queue for a worker
active	Currently processing
done	Completed successfully
failed	Failed with an error

Response — Active Job:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "progress": 0.45,
  "createdAt": 1709767500000,
  "updatedAt": 1709767520000
}

Response — Completed Render Job:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "done",
  "outputUrl": "https://peako.shin0x.space/assets/rendered-video-uuid.mp4",
  "createdAt": 1709767500000,
  "updatedAt": 1709767620000
}

Response — Completed Transcription Job:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "done",
  "captions": [
    { "id": "1", "from": 0,    "to": 2000, "text": "First caption" },
    { "id": "2", "from": 2000, "to": 4000, "text": "Second caption" }
  ],
  "createdAt": 1709767500000,
  "updatedAt": 1709767620000
}

Response — Failed Job:

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "error": "Video codec not supported",
  "createdAt": 1709767500000,
  "updatedAt": 1709767620000
}

Response Fields:

Field	Type	Present When
jobId	string	Always
status	string	Always
progress	number (0.0–1.0)	status = "active"
outputUrl	string	status = "done" for render/video-ops jobs
captions	array	status = "done" for transcription jobs
error	string	status = "failed"
createdAt	number	Always (Unix ms)
updatedAt	number	Always (Unix ms)

Error Codes:

• 200 — Job found
• 401 — Missing or invalid API key
• 404 — Job not found

Polling Example:

# Poll with jq
while true; do
  RESULT=$(curl -s -H "X-API-Key: $API_KEY" \
    https://peako.shin0x.space/api/jobs/$JOB_ID)
  STATUS=$(echo "$RESULT" | jq -r '.status')
  
  case "$STATUS" in
    done)
      echo "Complete: $(echo "$RESULT" | jq -r '.outputUrl')"
      break
      ;;
    failed)
      echo "Failed: $(echo "$RESULT" | jq -r '.error')"
      exit 1
      ;;
    active)
      PROGRESS=$(echo "$RESULT" | jq -r '.progress')
      echo "Progress: $(echo "$PROGRESS * 100" | bc)%"
      ;;
    queued)
      echo "Queued..."
      ;;
  esac
  sleep 5
done

Recommended Poll Intervals:

Content Length	Poll Interval
< 30 seconds	Every 2–5 seconds
30 seconds – 5 minutes	Every 10 seconds
> 5 minutes	Every 30 seconds

---

List Jobs

GET /api/jobs

List all jobs for the authenticated user.

Headers:

• X-API-Key: <your-api-key> (required)

Response:

{
  "jobs": [
    {
      "id": "job-uuid-1",
      "type": "PEAKO_RENDER",
      "status": "done",
      "progress": 1.0,
      "createdAt": 1709767620000,
      "outputUrl": "https://peako.shin0x.space/assets/output-uuid.mp4"
    },
    {
      "id": "job-uuid-2",
      "type": "PEAKO_TRANSCRIBE",
      "status": "active",
      "progress": 0.5,
      "createdAt": 1709767500000
    }
  ],
  "activeWorkers": 2,
  "totalWorkers": 4,
  "maxWorkers": 4,
  "isTeamOwner": false
}

Job Types:

Type	Description
PEAKO_RENDER	Template render job
PEAKO_TRANSCRIBE	Transcription job
PEAKO_TRIM	Video trim operation
PEAKO_MERGE	Video merge operation
PEAKO_MUTE	Mute operation
PEAKO_ADD_AUDIO	Add audio operation
PEAKO_SUBTITLE	Subtitle burn-in operation
PEAKO_BLUR	Blur operation
PEAKO_SPEED_RAMP	Speed ramp operation

---

Cancel Job

DELETE /api/jobs/:jobId

Cancel a queued job. Cannot cancel active, completed, or failed jobs.

Headers:

• X-API-Key: <your-api-key> (required)

Response (200 — Cancelled):

{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled"
}

Error Codes:

• 200 — Job cancelled
• 401 — Missing or invalid API key
• 404 — Job not found
• 409 — Cannot cancel — job is active, done, or failed

---

Job Retention

• Jobs and their metadata are retained for 7 days after completion
• Output files (outputUrl) are accessible for 7 days after the job completes
• After 7 days, jobs and files are automatically purged

---

Next: Video Operations