Get Job Status

GET

api

jobs

{id}

Get Job Status

curl --request GET \
  --url https://api.example.com/api/v1/jobs/{id}

<?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))

}

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

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.

Get Job Status

curl --request GET \
  --url https://api.example.com/api/v1/jobs/{id}

<?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))

}

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": {}
}

Overview

Completions

Media Generation

Audio

Skills API

E.V.I. Canvas

Workflows

Hooks

Settings

Embed Widgets

Guardrails

Routing Studio

Theo Browser

Benchmarks

Webhooks

Billing

Resources

Authentication

Path Parameters

Request Examples

Response

Example Response (Completed)

Example Response (In Progress)

Result schemas by type

Endpoint

​Authentication

​Path Parameters

​Request Examples

​Response

​Example Response (Completed)

​Example Response (In Progress)

​Result schemas by type

​Endpoint

Authentication

Path Parameters

Request Examples

Response

Example Response (Completed)

Example Response (In Progress)

Result schemas by type

Endpoint