> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Job Status

> Poll the status of an asynchronous job (video, research, etc.).

Get the current status of an asynchronous job. Used to poll for results from [Video](/api-reference/video/generate) and [Research](/api-reference/research/create) endpoints.

## Authentication

Requires a Bearer token. See [Authentication](/api-reference/authentication).

## Path Parameters

<ParamField path="id" type="string" required>
  The job ID returned by the async endpoint (e.g., `job_xyz789`).
</ParamField>

## Request Examples

<CodeGroup>
  ```bash curl theme={null}
  curl https://www.hitheo.ai/api/v1/jobs/job_xyz789 \
    -H "Authorization: Bearer $THEO_API_KEY"
  ```

  ```typescript SDK theme={null}
  // 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);
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string">
  Job ID.
</ResponseField>

<ResponseField name="type" type="string">
  Job type (e.g., `"video"`, `"research"`).
</ResponseField>

<ResponseField name="status" type="string">
  Current status: `"queued"`, `"active"`, `"completed"`, or `"failed"`.
</ResponseField>

<ResponseField name="progress" type="number">
  Progress percentage (0–100).
</ResponseField>

<ResponseField name="result" type="object | null">
  The job result. `null` until status is `"completed"`. The shape depends on the job `type` — see [Result schemas by type](#result-schemas-by-type) below. Any provider/model identifiers are always Theo-branded (`engine` / `model`), never raw upstream names.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if status is `"failed"`.
</ResponseField>

<ResponseField name="created_at" type="string | null">
  When the job was created.
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  When the job completed (or failed).
</ResponseField>

### Example Response (Completed)

`result` is an **object**, not a bare URL. For a video job:

```json theme={null}
{
  "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)

```json theme={null}
{
  "id": "job_xyz789",
  "type": "research",
  "status": "active",
  "progress": 45,
  "result": null,
  "error": null,
  "created_at": "2026-04-10T12:00:00Z",
  "completed_at": null
}
```

<Tip>
  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](/guides/async-jobs).
</Tip>

## 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`**

```json theme={null}
{
  "report": "# Markdown report with inline citations...",
  "sources": [{ "title": "Source title", "url": "https://..." }],
  "queries": ["generated search query"],
  "sourceCount": 8
}
```

**`video`**

```json theme={null}
{ "videoUrl": "https://...", "model": "Theo Motion", "engine": "theo-motion", "durationMs": 90000 }
```

**`image`**

```json theme={null}
{ "imageUrl": "https://...", "model": "Theo Studio", "engine": "theo-studio" }
```

**`document`**

```json theme={null}
{ "title": "Report", "format": "pdf", "downloadUrl": "https://...", "sizeBytes": 248000 }
```

## Endpoint

`GET /api/v1/jobs/{id}`

Requires authentication via Bearer token. See [Authentication](/api-reference/authentication).