Async Jobs (Research & Video)

​

Lifecycle

1. Enqueue — POST /api/v1/research or /api/v1/video returns 202 with { id, job_id, status: "queued", poll_url }.
2. Poll — GET /api/v1/jobs/{job_id} returns the current status: queued → active → completed (or failed).
3. Read the result — when status === "completed", result holds the typed payload.

​

SDK usage

import { Theo, type ResearchJobResult } from "@hitheo/sdk";

const theo = new Theo({ apiKey: process.env.THEO_API_KEY! });

const job = await theo.research({
  prompt: "Compare React, Vue, and Svelte for enterprise apps in 2026",
  depth: "advanced",
  max_sources: 10,
});

const final = await theo.waitForJob<ResearchJobResult>(job.job_id, {
  intervalMs: 3000,                       // poll cadence (default 2s)
  maxWaitMs: 180_000,                      // give up after 3 min (default 5 min)
  onProgress: (s) => console.log(`${s.status} ${s.progress}%`),
  signal: AbortSignal.timeout(180_000),   // optional hard cancel
});

if (final.status === "completed") {
  console.log(final.result?.report);
  console.log(`${final.result?.sourceCount} sources`);
}

​

Polling cadence & limits

• Default poll interval is 2s; waitForJob gives up after 5 minutes by default (maxWaitMs) and throws a TheoTimeoutError. Raise maxWaitMs for long video renders.
• Don’t poll faster than ~1s — it wastes rate-limit budget without finishing the job any sooner.

​

Cancellation

const controller = new AbortController();
// e.g. user navigates away
document.addEventListener("stop", () => controller.abort());

await theo.waitForJob(job.job_id, { signal: controller.signal });

​

Result schemas

• ResearchJobResult — { report, sources: { title, url }[], queries, sourceCount }
• VideoJobResult — { videoUrl, model, engine, durationMs }
• ImageJobResult — { imageUrl, model, engine }
• DocumentJobResult — { title, format, downloadUrl, sizeBytes } Any model / engine fields are Theo-branded — raw upstream identifiers never appear.

​

Cost & usage

​

Failures