Jobs

GET /v1/jobs/:id

Check the status and progress of an asynchronous job.

Several operations (analyze, export, translate, voiceover) run asynchronously and return a jobId. Use this endpoint to poll for progress and results.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Job ID (e.g. analysis_..., export_..., translation_..., tool_...)

Example

curl https://api.vidocu.ai/v1/jobs/analysis_1708300000000_abc1234 \
  -H "Authorization: Bearer vdo_live_your_key_here"

Response 200 OK

{
  "jobId": "analysis_1708300000000_abc1234",
  "type": "analysis",
  "status": "processing",
  "progress": {
    "step": "transcribing",
    "message": "Creating video script...",
    "percentage": 45
  },
  "result": null,
  "error": null,
  "createdAt": "2024-02-19T10:00:00.000Z",
  "updatedAt": "2024-02-19T10:01:30.000Z"
}

Response fields

Field	Type	Description
jobId	string	Unique job identifier
type	string	analysis, export, translation, or tool
status	string	pending, processing, completed, or failed
progress	object | null	Current progress (when processing)
progress.step	string	Current processing step
progress.message	string	Human-readable progress message
progress.percentage	number | undefined	Completion percentage (0–100)
result	object | null	Result data (when completed)
error	string | null	Error message (when failed)
createdAt	string	Job creation timestamp
updatedAt	string	Last status update timestamp

Job statuses

Status	Description
pending	Job created, waiting to start
processing	Job is running
completed	Job finished successfully
failed	Job encountered an error

Polling pattern

Poll the job endpoint until status is completed or failed:

async function waitForJob(jobId: string, apiKey: string): Promise<any> {
  while (true) {
    const res = await fetch(`https://api.vidocu.ai/v1/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const job = await res.json();

    if (job.status === "completed") return job.result;
    if (job.status === "failed") throw new Error(job.error);

    // Wait 2 seconds between polls
    await new Promise((r) => setTimeout(r, 2000));
  }
}

For a better approach, use webhooks to receive notifications when jobs complete.

Errors

Status	Code	Cause
401	authentication_error	Invalid or missing API key
404	not_found	Job not found or belongs to a different workspace