> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Extract Task
> Poll extract task status and get download links
Check where an extract task is at. This comes back right away, so poll it every 5–10 seconds until `status` is `complete` or `failed`.
**Permissions.** You can only query tasks created by you or your organization — other tasks return `404`.
**Results expire after 1 hour.** Task records are kept for 1 hour after creation; afterwards polling returns `404 CS-UORC01-003`. Take your results within 1 hour of creating the task.
## State machine
`queued` → `processing` → `complete` | `failed`
## Response fields
| Field | Description |
| ------------ | ------------------------------------------------------------------------------------------------- |
| `task_id` | The extract task id |
| `kind` | `static_bin` or `dynamic_fbx` |
| `status` | `queued`, `processing`, `complete`, or `failed` |
| `result` | Present when `status` is `complete` — carries signed download links (see below). `null` otherwise |
| `error` | Short error label when `status` is `failed` |
| `error_code` | Structured error code when `status` is `failed` (e.g. `CS-UORC01-017`) |
## Terminal state: `complete`
When `status` is `complete`, `result` returns each artifact as a temporary signed download link via `*_url` / `*_urls` fields. Links are **valid for 1 hour and re-signed on every poll** — if a link expires, just `GET` again to receive a fresh one.
**static-bin** completed example:
```json theme={null}
{
"task_id": "ext_a1b2c3d4e5f60718",
"kind": "static_bin",
"status": "complete",
"created_at": "2026-06-12T08:00:00+00:00",
"updated_at": "2026-06-12T08:06:40+00:00",
"result": {
"success": true,
"stripped_bin_url": "https://storage.googleapis.com/...character_stripped.bin?X-Goog-Signature=...",
"render_output_urls": [
"https://storage.googleapis.com/...thumbnails/thumb0.png?X-Goog-Signature=..."
]
},
"error": null,
"error_code": null
}
```
For **dynamic-fbx**, `result` carries the `glb` / `fbx` download links (`glb_url`, `fbx_url`).
## Terminal state: `failed`
When the task fails, the `GET` itself returns **HTTP 200** — the failure is reported in the body's `status` / `error` / `error_code` fields.
```json theme={null}
{
"task_id": "ext_0f9e8d7c6b5a4332",
"kind": "dynamic_fbx",
"status": "failed",
"created_at": "2026-06-12T08:00:00+00:00",
"updated_at": "2026-06-12T08:02:10+00:00",
"result": null,
"error": "The extract task failed.",
"error_code": "CS-UORC01-017"
}
```
## Polling examples
```python Python theme={null}
import requests
import time
task_id = "ext_a1b2c3d4e5f60718"
url = f"https://apis.viggle.ai/api/extract/{task_id}"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
while True:
data = requests.get(url, headers=headers).json()
print(f"Status: {data['status']}")
if data["status"] == "complete":
print(data["result"])
break
elif data["status"] == "failed":
print(f"Error {data.get('error_code')}: {data.get('error')}")
break
time.sleep(5)
```
```javascript JavaScript theme={null}
const taskId = "ext_a1b2c3d4e5f60718";
const url = `https://apis.viggle.ai/api/extract/${taskId}`;
const headers = { "Authorization": "Bearer YOUR_API_KEY" };
while (true) {
const data = await fetch(url, { headers }).then(r => r.json());
console.log(`Status: ${data.status}`);
if (data.status === "complete") {
console.log(data.result);
break;
} else if (data.status === "failed") {
console.error(`Error ${data.error_code}: ${data.error}`);
break;
}
await new Promise(r => setTimeout(r, 5000));
}
```
```bash cURL theme={null}
curl -s "https://apis.viggle.ai/api/extract/ext_a1b2c3d4e5f60718" \
-H "Authorization: Bearer YOUR_API_KEY"
```
## OpenAPI
````yaml GET /api/extract/{task_id}
openapi: 3.0.3
info:
title: Viggle API
description: Generate AI-powered character animation videos
version: 2.0.0
contact:
name: Viggle Support
url: https://viggle.ai
servers:
- url: https://apis.viggle.ai
description: Production server
security: []
paths:
/api/extract/{task_id}:
get:
tags:
- Extract
summary: Get Extract Task
description: >-
Poll extract task status. You can only query tasks created by you or
your organization — otherwise 404. When status is complete, result
carries temporary signed download links (valid 1 hour, re-signed on
every poll). When the task fails, this endpoint still returns HTTP 200
with status, error, and error_code in the body. Task records are kept
for 1 hour; afterwards polling returns 404. Suggested polling interval:
5–10 seconds.
operationId: getExtractTask
parameters:
- name: task_id
in: path
required: true
schema:
type: string
example: ext_a1b2c3d4e5f60718
responses:
'200':
description: Extract task status
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractTask'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Task not found or expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorStructured'
example:
detail:
error_code: CS-UORC01-003
message: >-
Task not found. It may have expired — task records are kept
for 1 hour after creation.
security:
- bearerAuth: []
components:
schemas:
ExtractTask:
type: object
properties:
task_id:
type: string
example: ext_a1b2c3d4e5f60718
kind:
type: string
enum:
- static_bin
- dynamic_fbx
example: static_bin
status:
type: string
enum:
- queued
- processing
- complete
- failed
description: Task status. Poll until complete or failed.
created_at:
type: string
format: date-time
nullable: true
example: '2026-06-12T08:00:00+00:00'
updated_at:
type: string
format: date-time
nullable: true
example: '2026-06-12T08:03:21+00:00'
result:
type: object
nullable: true
description: >-
Present when status is complete. Carries temporary signed download
links via *_url / *_urls fields (valid 1 hour, re-signed on every
poll). For static_bin: stripped_bin_url, render_output_urls. For
dynamic_fbx: glb_url, fbx_url.
properties:
success:
type: boolean
example: true
stripped_bin_url:
type: string
format: uri
description: Signed download link for character_stripped.bin (static_bin).
render_output_urls:
type: array
description: >-
Signed download links for rendered thumbnails (static_bin, when
render_thumbnail=true).
items:
type: string
format: uri
glb_url:
type: string
format: uri
description: Signed download link for animation.glb (dynamic_fbx).
fbx_url:
type: string
format: uri
description: Signed download link for animation.fbx (dynamic_fbx).
error:
type: string
nullable: true
description: Short error label when status is failed.
example: The extract task failed.
error_code:
type: string
nullable: true
description: Structured error code when status is failed (e.g. CS-UORC01-017).
example: CS-UORC01-017
ErrorStructured:
type: object
description: >-
Structured error. `detail` carries a machine-readable `error_code` plus
a human-readable `message`.
properties:
detail:
type: object
properties:
error_code:
type: string
example: CS-UORC01-008
message:
type: string
example: Insufficient credits. Top up your balance to continue.
Error:
type: object
description: >-
Simple error. `detail` is a human-readable message (used for auth
errors).
properties:
detail:
type: string
example: 'API key required. Use Authorization: Bearer sk-xxx'
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
detail: >-
Invalid or missing API key. Pass it as Authorization: Bearer
sk-...
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key passed as Bearer token
````