Resources
Get Job Status
Poll the status of an asynchronous job (video, research, etc.).
GET
/
api
/
v1
/
jobs
/
{id}
Get Job Status
curl --request GET \
--url https://api.example.com/api/v1/jobs/{id}import requests
url = "https://api.example.com/api/v1/jobs/{id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/jobs/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/jobs/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/jobs/{id}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/jobs/{id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/jobs/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"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
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"
// Single poll
const status = await theo.job("job_xyz789");
console.log(status.status, status.progress);
// Auto-poll until complete (recommended)
const result = await theo.waitForJob("job_xyz789");
console.log(result.result);
Response
string
Job ID.
string
Job type (e.g.,
"video", "research").string
Current status:
"queued", "active", "completed", or "failed".number
Progress percentage (0–100).
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.string | null
Error message if status is
"failed".string | null
When the job was created.
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
Theresult 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.Was this page helpful?
Get Job Status
curl --request GET \
--url https://api.example.com/api/v1/jobs/{id}import requests
url = "https://api.example.com/api/v1/jobs/{id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://api.example.com/api/v1/jobs/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/jobs/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/jobs/{id}"
req, _ := http.NewRequest("GET", url, nil)
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/jobs/{id}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/jobs/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"id": "<string>",
"type": "<string>",
"status": "<string>",
"progress": 123,
"result": {},
"error": {},
"created_at": {},
"completed_at": {}
}