Jobs

GET /v1/jobs/:id

Check the status and progress of an asynchronous job.

Lost a job ID?

GET /v1/jobs lists recent jobs for your workspace, newest first.

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)
errorCode	string | null	Machine-readable reason when failed and the caller can act on it. Today: no_speech, transcription_failed (analysis jobs with scriptSource: "transcript").
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

---

List jobs

GET /v1/jobs

List recent jobs for your workspace, newest first. Useful when you've lost a jobId, or to check whether anything is still running before you start more work.

Query parameters

Parameter	Type	Default	Description
status	string	-	pending, processing, completed, or failed
type	string	-	export, analysis, translation, tool, or process
page	number	1	Page number
limit	number	20	Jobs per page, max 100
cursor	string	-	nextCursor from a previous response. Overrides page.

Example

curl "https://api.vidocu.ai/v1/jobs?status=processing&limit=10" \
  -H "Authorization: Bearer vdo_live_your_key_here"

Response 200 OK

{
  "jobs": [
    {
      "jobId": "export_1754739600000_a1b2c3",
      "type": "export",
      "status": "processing",
      "progress": { "step": "rendering", "percent": 42 },
      "error": null,
      "createdAt": "2026-08-09T10:20:00.000Z",
      "updatedAt": "2026-08-09T10:21:30.000Z"
    }
  ],
  "pagination": { "total": 37, "page": 1, "limit": 10, "totalPages": 4, "nextCursor": "eyJ0Ijoi..." }
}

The list omits result - fetch the single job to get it, so a page of completed jobs doesn't carry every payload.

Errors

Status	Code	Cause
400	validation_error	Unknown status or type, or limit out of range
401	authentication_error	Invalid or missing API key