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://www.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
object | null
The job result. null until status is "completed". The shape depends on the job type — see Result schemas by type below. Any provider/model identifiers are always Theo-branded (engine / model), never raw upstream names.
​
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)

result is an object, not a bare URL. For a video job: 
{
  "id": "job_xyz789",
  "type": "video",
  "status": "completed",
  "progress": 100,
  "result": {
    "videoUrl": "https://artifacts.hitheo.ai/video/xyz789.mp4",
    "model": "Theo Motion",
    "engine": "theo-motion",
    "durationMs": 90000
  },
  "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, signal, onProgress }) polls automatically with a configurable interval (default 2s), overall timeout (default 5 minutes), an optional AbortSignal, and an onProgress callback. The legacy positional form waitForJob(id, intervalMs, maxWaitMs) still works. See the Async Jobs guide.

​
Result schemas by type

The result object differs per job type. These mirror the SDK’s typed result interfaces (ResearchJobResult, VideoJobResult, ImageJobResult, DocumentJobResult) — poll with theo.waitForJob<VideoJobResult>(...) to get them typed. research 
{
  "report": "# Markdown report with inline citations...",
  "sources": [{ "title": "Source title", "url": "https://..." }],
  "queries": ["generated search query"],
  "sourceCount": 8
}
video 
{ "videoUrl": "https://...", "model": "Theo Motion", "engine": "theo-motion", "durationMs": 90000 }
image 
{ "imageUrl": "https://...", "model": "Theo Studio", "engine": "theo-studio" }
document 
{ "title": "Report", "format": "pdf", "downloadUrl": "https://...", "sizeBytes": 248000 }

​
Endpoint

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