Skip to main content
GET
/
api
/
v1
/
jobs
/
{id}
Get Job Status
curl --request GET \
  --url https://api.example.com/api/v1/jobs/{id}
{
  "id": "<string>",
  "type": "<string>",
  "status": "<string>",
  "progress": 123,
  "result": {},
  "error": {},
  "created_at": {},
  "completed_at": {}
}
Get the current status of an asynchronous job. Used to poll for results from Video and Research endpoints.

​
Authentication

Requires a Bearer token. See Authentication.

​
Path Parameters

​
id
string
required
The job ID returned by the async endpoint (e.g., job_xyz789).

​
Request Examples

curl https://hitheo.ai/api/v1/jobs/job_xyz789 \
  -H "Authorization: Bearer $THEO_API_KEY"

​
Response

​
id
string
Job ID.
​
type
string
Job type (e.g., "video", "research").
​
status
string
Current status: "queued", "active", "completed", or "failed".
​
progress
number
Progress percentage (0–100).
​
result
any | null
The job result. null until status is "completed". Contents depend on the job type (e.g., video URL, research report).
​
error
string | null
Error message if status is "failed".
​
created_at
string | null
When the job was created.
​
completed_at
string | null
When the job completed (or failed).

​
Example Response (Completed)

{
  "id": "job_xyz789",
  "type": "video",
  "status": "completed",
  "progress": 100,
  "result": "https://artifacts.hitheo.ai/video/xyz789.mp4",
  "error": null,
  "created_at": "2026-04-10T12:00:00Z",
  "completed_at": "2026-04-10T12:01:30Z"
}

​
Example Response (In Progress)

{
  "id": "job_xyz789",
  "type": "research",
  "status": "active",
  "progress": 45,
  "result": null,
  "error": null,
  "created_at": "2026-04-10T12:00:00Z",
  "completed_at": null
}
The SDK’s theo.waitForJob(jobId, intervalMs, maxWaitMs) polls automatically with configurable interval (default 2s) and timeout (default 5 minutes).

​
Endpoint

GET /api/v1/jobs/{id} Requires authentication via Bearer token. See Authentication.